Merge pull request #28 from CosmWasm/API-docs

API docs

crates/cw-storey/src/backend.rs

@@ -1,5 +1,6 @@
 use storey::storage::{StorageBackend, StorageBackendMut};
 
+/// A wrapper around a type implementing [`cosmwasm_std::Storage`] that integrates it with [`storey`].
 pub struct CwStorage<S>(pub S);
 
 impl<S> StorageBackend for CwStorage<S>

crates/cw-storey/src/containers.rs

@@ -1,4 +1,17 @@
+//! Storage containers for use with [*CosmWasm*] smart contracts.
+//!
+//! [*CosmWasm*]: https://github.com/CosmWasm/cosmwasm
+
+/// The [`storey::containers::Item`] type with the default encoding for [*CosmWasm*] smart
+/// contracts.
+///
+/// [*CosmWasm*]: https://github.com/CosmWasm/cosmwasm
 pub type Item<T> = storey::containers::Item<T, crate::encoding::CwEncoding>;
+
+/// The [`storey::containers::Column`] type with the default encoding for [*CosmWasm*] smart
+/// contracts.
+///
+/// [*CosmWasm*]: https://github.com/CosmWasm/cosmwasm
 pub type Column<T> = storey::containers::Column<T, crate::encoding::CwEncoding>;
 
 pub use storey::containers::Map;

crates/cw-storey/src/encoding.rs

@@ -1,5 +1,14 @@
 use storey::encoding::{Cover, DecodableWithImpl, EncodableWithImpl, Encoding};
 
+/// A simple encoding that uses [*MessagePack*] to encode and decode data.
+///
+/// This type implements the [`Encoding`] trait (see [`storey::encoding`]), which means it can
+/// be used with some of [`storey`]'s containers to encode and decode values.
+///
+/// You're unlikely to need to use this type directly for basic library usage. You might
+/// need it if you're trying to use third-party containers this crate does not provide.
+///
+/// [*MessagePack*]: https://msgpack.org/
 pub struct CwEncoding;
 
 impl Encoding for CwEncoding {

crates/cw-storey/src/lib.rs

@@ -1,5 +1,18 @@
+//! An integration of [`storey`] with [*CosmWasm*].
+//!
+//! This crate provides
+//! - a [*CosmWasm*] storage backend for use with [`storey`] collections,
+//! - a [*MessagePack*] encoding integration to be used for serializing and deserializing
+//! values, and
+//! - a set of container re-exports that remove the need to manually specify the
+//! encoding, instead relying on the default [*MessagePack*] encoding.
+//!
+//! [*CosmWasm*]: https://github.com/CosmWasm/cosmwasm
+//! [*MessagePack*]: https://msgpack.org/
+
 mod backend;
 pub mod containers;
 mod encoding;
 
 pub use backend::CwStorage;
+pub use encoding::CwEncoding;

crates/storey-encoding/src/lib.rs

@@ -1,5 +1,8 @@
 pub trait Encoding {
+    /// The error type returned when encoding fails.
     type EncodeError;
+
+    /// The error type returned when decoding fails.
     type DecodeError;
 }
 

crates/storey-storage/src/backend.rs

@@ -1,15 +1,30 @@
 use super::storage::{Storage, StorageMut};
 
+/// A trait for immutably accessing a storage backend.
+///
+/// A collection of basic read operations that can be performed on a storage backend.
+///
+/// You should only have to interact with this trait if you are implementing a custom storage backend.
 pub trait StorageBackend {
+    /// Get the value associated with the given key.
     fn get(&self, key: &[u8]) -> Option<Vec<u8>>;
 
+    /// Check if the given key exists in the storage backend.
     fn has(&self, key: &[u8]) -> bool {
         self.get(key).is_some()
     }
 }
 
+/// A trait for mutably accessing a storage backend.
+///
+/// A collection of basic write operations that can be performed on a storage backend.
+///
+/// You should only have to interact with this trait if you are implementing a custom storage backend.
 pub trait StorageBackendMut {
+    /// Set the value associated with the given key.
     fn set(&mut self, key: &[u8], value: &[u8]);
+
+    /// Remove the value associated with the given key.
     fn remove(&mut self, key: &[u8]);
 }
 

crates/storey-storage/src/storage.rs

@@ -1,37 +1,87 @@
+/// A read interface for binary key-value storage.
 pub trait Storage {
+    /// Get the value of the key.
     fn get(&self, key: &[u8]) -> Option<Vec<u8>>;
 
+    /// Check if the key exists.
     fn has(&self, key: &[u8]) -> bool {
         self.get(key).is_some()
     }
 
+    /// Get the value of the key in the metadata namespace.
     fn get_meta(&self, _key: &[u8]) -> Option<Vec<u8>>;
+
+    /// Check if the key exists in the metadata namespace.
     fn has_meta(&self, key: &[u8]) -> bool {
         self.get_meta(key).is_some()
     }
 }
 
+/// A write interface for binary key-value storage.
 pub trait StorageMut {
+    /// Set the value of the key.
     fn set(&mut self, key: &[u8], value: &[u8]);
+
+    /// Remove the key.
     fn remove(&mut self, key: &[u8]);
 
+    /// Set the value of the key in the metadata namespace.
     fn set_meta(&mut self, _key: &[u8], _value: &[u8]);
+
+    /// Remove the key in the metadata namespace.
     fn remove_meta(&mut self, _key: &[u8]);
 }
 
+/// Iteration interface for binary key-value storage.
+///
+/// The iterator should iterate over key-value pairs in lexicographical order of keys.
 pub trait IterableStorage {
+    /// The type of the iterator returned by [`keys`](Self::keys).
     type KeysIterator<'a>: Iterator<Item = Vec<u8>>
     where
         Self: 'a;
+
+    /// The type of the iterator returned by [`values`](Self::values).
     type ValuesIterator<'a>: Iterator<Item = Vec<u8>>
     where
         Self: 'a;
+
+    /// The type of the iterator returned by [`pairs`](Self::pairs).
     type PairsIterator<'a>: Iterator<Item = (Vec<u8>, Vec<u8>)>
     where
         Self: 'a;
 
+    /// Get an iterator over keys.
+    ///
+    /// The iterator should iterate over keys in lexicographical order.
+    ///
+    /// If `start` is `None`, the iterator should start from the first key.
+    /// If `end` is `None`, the iterator should iterate until the last key.
+    /// If both `start` and `end` are `None`, the iterator should iterate over all keys.
+    ///
+    /// The range is inclusive for `start` and exclusive for `end`.
     fn keys<'a>(&'a self, start: Option<&[u8]>, end: Option<&[u8]>) -> Self::KeysIterator<'a>;
+
+    /// Get an iterator over values.
+    ///
+    /// The iterator should iterate over values corresponding to keys in lexicographical order.
+    ///
+    /// If `start` is `None`, the iterator should start from the first key.
+    /// If `end` is `None`, the iterator should iterate until the last key.
+    /// If both `start` and `end` are `None`, the iterator should iterate over all keys.
+    ///
+    /// The range is inclusive for `start` and exclusive for `end`.
     fn values<'a>(&'a self, start: Option<&[u8]>, end: Option<&[u8]>) -> Self::ValuesIterator<'a>;
+
+    /// Get an iterator over key-value pairs.
+    ///
+    /// The iterator should iterate over key-value pairs in lexicographical order.
+    ///
+    /// If `start` is `None`, the iterator should start from the first key.
+    /// If `end` is `None`, the iterator should iterate until the last key.
+    /// If both `start` and `end` are `None`, the iterator should iterate over all keys.
+    ///
+    /// The range is inclusive for `start` and exclusive for `end`.
     fn pairs<'a>(&'a self, start: Option<&[u8]>, end: Option<&[u8]>) -> Self::PairsIterator<'a>;
 }
 
@@ -40,14 +90,41 @@ impl<T: IterableStorage> IterableStorage for &T {
     type ValuesIterator<'a> = T::ValuesIterator<'a> where Self: 'a;
     type PairsIterator<'a> = T::PairsIterator<'a> where Self: 'a;
 
+    /// Get an iterator over keys.
+    ///
+    /// The iterator should iterate over keys in lexicographical order.
+    ///
+    /// If `start` is `None`, the iterator should start from the first key.
+    /// If `end` is `None`, the iterator should iterate until the last key.
+    /// If both `start` and `end` are `None`, the iterator should iterate over all keys.
+    ///
+    /// The range is inclusive for `start` and exclusive for `end`.
     fn keys<'a>(&'a self, start: Option<&[u8]>, end: Option<&[u8]>) -> Self::KeysIterator<'a> {
         (**self).keys(start, end)
     }
 
+    /// Get an iterator over values.
+    ///
+    /// The iterator should iterate over values corresponding to keys in lexicographical order.
+    ///
+    /// If `start` is `None`, the iterator should start from the first key.
+    /// If `end` is `None`, the iterator should iterate until the last key.
+    /// If both `start` and `end` are `None`, the iterator should iterate over all keys.
+    ///
+    /// The range is inclusive for `start` and exclusive for `end`.
     fn values<'a>(&'a self, start: Option<&[u8]>, end: Option<&[u8]>) -> Self::ValuesIterator<'a> {
         (**self).values(start, end)
     }
 
+    /// Get an iterator over key-value pairs.
+    ///
+    /// The iterator should iterate over key-value pairs in lexicographical order.
+    ///
+    /// If `start` is `None`, the iterator should start from the first key.
+    /// If `end` is `None`, the iterator should iterate until the last key.
+    /// If both `start` and `end` are `None`, the iterator should iterate over all keys.
+    ///
+    /// The range is inclusive for `start` and exclusive for `end`.
     fn pairs<'a>(&'a self, start: Option<&[u8]>, end: Option<&[u8]>) -> Self::PairsIterator<'a> {
         (**self).pairs(start, end)
     }
@@ -71,13 +148,21 @@ impl<T: IterableStorage> IterableStorage for &mut T {
     }
 }
 
+/// Iteration interface for binary key-value storage in reverse order.
+///
+/// The iterator should iterate over key-value pairs in reverse lexicographical order of keys.
 pub trait RevIterableStorage {
+    /// The type of the iterator returned by [`rev_keys`](Self::rev_keys).
     type RevKeysIterator<'a>: Iterator<Item = Vec<u8>>
     where
         Self: 'a;
+
+    /// The type of the iterator returned by [`rev_values`](Self::rev_values).
     type RevValuesIterator<'a>: Iterator<Item = Vec<u8>>
     where
         Self: 'a;
+
+    /// The type of the iterator returned by [`rev_pairs`](Self::rev_pairs).
     type RevPairsIterator<'a>: Iterator<Item = (Vec<u8>, Vec<u8>)>
     where
         Self: 'a;