Update documents (#58)

README.md

@@ -3,9 +3,27 @@
 ![GitHub Workflow Status](https://img.shields.io/github/workflow/status/second-state/SewUp/CI)
 [![Generic badge](https://img.shields.io/badge/Doc-main-green.svg)](https://second-state.github.io/SewUp/sewup/)
 
-**S**econdstate **EW**asm **U**tility **P**rogram, a library to help you sew up your Ethereum project with Rust and just like develop in a common backend.
+**S**econdstate **EW**asm **U**tility **P**rogram, a library to help you sew up your Ethereum project with Rust and just like develop in a common backend.  
 
 ## Slides
-| Date       | Event                  | Slides                                          |
-|------------|------------------------|-------------------------------------------------|
-| 2021/06/19 | Rust meetup (Beijing ) | [v0.0.1-pre](https://slides.com/yanganto/sewup) |
+| Date       | Event                 | Slides                                          |
+|------------|-----------------------|-------------------------------------------------|
+| 2021/06/19 | Rust meetup (Beijing) | [v0.0.1-pre](https://slides.com/yanganto/sewup) |
+
+## Usage
+Add the `sewup` with the feature and the `sewup-derive` into Cargo.toml, and setup lib section as following, then you are ready to build contract with sewup.  
+```toml
+[lib]
+path = "src/lib.rs"
+crate-type = ["cdylib"]
+
+[dependencies]
+sewup = { version = "0.0.1", features = ['kv'] }
+sewup-derive = { version = "0.0.1" }
+```
+Besides, you can take `/kv-contract` as an example.
+
+## Development
+The workspace have several project, the contract project should build with target `wasm32-unknown-unknown` and the flag `-Clink-arg=--export-table`.  
+After placing the `.wasm` output into `/resources`, you can run `cargo test -p sewup --features=kv` to check on the test for kv features.  
+It is easy to participate with help want issues and the good first issues.  

sewup/src/kv/bucket.rs

@@ -1,3 +1,6 @@
+//! Bucket is an abstract concept to help you storage key value items.
+//! The types of key and value should be specific when new a bucket.
+//! Items save into bucket may have different encoding, the will base on the feature you enabled.
 use std::marker::PhantomData;
 
 use anyhow::Result;
@@ -7,12 +10,12 @@ use crate::kv::traits::key::AsHashKey;
 use crate::types::{Raw, Row};
 
 // TODO: quick for first iteration
+/// `RawBucket` is a structure the data format really store
+/// The hash key is stored in the first item, and the `Key` and `Value` are
+/// stored in the second item
 pub type RawBucket = (Vec<Raw>, Vec<Raw>);
 
-/// Bucket is an abstract concept to help you storage key value items.
-/// The types of key and value should be specific when new a bucket.
-/// Items save into bucket may have different encoding, the will base on the
-/// feature you enabled.
+/// Bucket is a wrapper for `RawBucket`, including the name of the bucket
 pub struct Bucket<K: Key, V: Value> {
     pub(crate) name: String,
     pub(crate) raw_bucket: RawBucket,
@@ -69,6 +72,7 @@ impl<'a, K: Key, V: Value> Iterator for Iter<'a, K, V> {
 }
 
 impl<'a, K: Key, V: Clone + Value> Bucket<K, V> {
+    /// New a `Bucket` with name
     pub fn new(name: String, raw_bucket: RawBucket) -> Bucket<K, V> {
         Bucket {
             name,
@@ -78,6 +82,7 @@ impl<'a, K: Key, V: Clone + Value> Bucket<K, V> {
         }
     }
 
+    /// Check the `Key` in the bucket
     pub fn contains(&self, key: K) -> Result<bool> {
         let hash = key.gen_hash()?;
 
@@ -92,6 +97,7 @@ impl<'a, K: Key, V: Clone + Value> Bucket<K, V> {
         Ok(false)
     }
 
+    /// Get a `Value` from bucket by `Key`
     pub fn get(&self, key: K) -> Result<Option<V>> {
         let hash = key.gen_hash()?;
 
@@ -112,6 +118,7 @@ impl<'a, K: Key, V: Clone + Value> Bucket<K, V> {
         Ok(None)
     }
 
+    /// Set an item into the bucket
     pub fn set(&mut self, key: K, value: V) -> Result<()> {
         let mut value: Vec<Raw> = value.to_raw_value()?.into();
         let mut raw_key: Vec<Raw> = key.to_raw_key()?.into();
@@ -127,6 +134,7 @@ impl<'a, K: Key, V: Clone + Value> Bucket<K, V> {
         Ok(())
     }
 
+    /// Remove a item from the bucket by key
     pub fn remove(&mut self, key: K) -> Result<()> {
         let hash = key.gen_hash()?;
 
@@ -148,6 +156,7 @@ impl<'a, K: Key, V: Clone + Value> Bucket<K, V> {
         Ok(())
     }
 
+    /// Iterate all the items in the bucket
     pub fn iter(&self) -> Iter<K, V> {
         return Iter {
             raw_bucket: &self.raw_bucket,
@@ -159,7 +168,7 @@ impl<'a, K: Key, V: Clone + Value> Bucket<K, V> {
         };
     }
 
-    /// May not work
+    /// Iterate the items in the bucket with specific range
     pub fn iter_range(&self, start: usize, end: usize) -> Iter<K, V> {
         return Iter {
             raw_bucket: &self.raw_bucket,
@@ -171,27 +180,27 @@ impl<'a, K: Key, V: Clone + Value> Bucket<K, V> {
         };
     }
 
-    /// May not work
+    /// Iterate the times with special prefix
     pub fn iter_prefix(&self, prefix: K) -> Iter<K, V> {
         unimplemented!();
     }
 
-    /// Native only, return an watch object, May not work
-    pub fn watch(&self, key: K) -> Result<()> {
-        unimplemented!();
-    }
+    // Always watch a Item among the blocks
+    // pub fn watch(&self, key: K) -> Result<()> {
+    //     unimplemented!();
+    // }
 
     /// Get previous key, value pair
     pub fn prev_key(&self, key: K) -> Result<Option<Item<K, V>>> {
         unimplemented!();
     }
 
-    /// Get next key value paire
+    /// Get next key value pair
     pub fn next_key(&self, key: K) -> Result<Option<Item<K, V>>> {
         unimplemented!();
     }
 
-    /// Pop items
+    /// Pop item with specific key
     pub fn pop(&self, key: K) -> Result<Option<V>> {
         unimplemented!();
     }
@@ -206,10 +215,12 @@ impl<'a, K: Key, V: Clone + Value> Bucket<K, V> {
         Ok(None)
     }
 
+    /// Get the length of the bucket
     pub fn len(&self) -> usize {
         self.raw_bucket.0.len()
     }
 
+    /// Check there is something in the bucket
     pub fn is_empty(&self) -> bool {
         self.raw_bucket.0.is_empty()
     }

sewup/src/kv/mod.rs

@@ -14,25 +14,19 @@
 //! > sewup = { features = ["kv"] }
 //!
 //! ```ignore
-//! use sewup::kv::*;
+//! use sewup::kv::Store;
+//! use sewup::types::{Raw, Row};
 //!
-//! let store = Store::new()?;
-//! let bucket = Store.bucket::<Raw, Raw>("default")?;
+//! let mut store = Store::new().unwrap();
+//! let mut bucket = store.bucket::<Raw, Raw>("default").unwrap();
 //!
 //! // Set testing = 123
-//! bucket.set(b"test", b"123")?;
-//! assert!(bucket.get(b"test").unwrap().unwrap() == "123");
-//! assert!(bucket.get(b"not exist").unwrap() == None);
+//! bucket.set(b"test".into(), b"123".into());
 //!
 //! // Set store with specific types
-//! let bucket2 = Store.bucket::<Integer, String>("bucket2")?;
-//! bucket2.set(1, "Testing");
+//! let mut bucket2 = store.bucket::<Raw, Row>("bucket2").unwrap();
+//! bucket2.set(b"long".into(), "Testing".to_string().into());
 //! ```
-//!
-//! These serialization features will be support
-//! 1. msgpack
-//! 2. bincode
-//! 3. json
 
 //TODO: remove this after implement
 #[allow(unused_variables)]

sewup/src/kv/store.rs

@@ -177,6 +177,7 @@ impl Store {
             .to_le_bytes()
             .swap_with_slice(&mut buffer[1..3]);
 
+        // TODO: store as really need
         let bin = bincode::serialize(&self.tenants).expect("serialize db binary fail");
         let length = bin.len();
 

sewup/src/types/raw.rs

@@ -5,6 +5,7 @@ use serde_derive::Deserialize;
 
 use crate::types::*;
 
+/// The small storage unit in the contract, which contains 32 bytes.
 #[derive(Clone)]
 pub struct Raw {
     pub(crate) bytes: [u8; 32],

sewup/src/types/row.rs

@@ -4,6 +4,7 @@ use serde_derive::{Deserialize, Serialize};
 
 use crate::types::*;
 
+/// A list of `Raw`, which helps you store much bigger data than a `Raw`
 #[derive(Clone, Serialize, Deserialize)]
 pub struct Row {
     pub(super) inner: Vec<Raw>,