[ink_storage] Add missing docs for ink_storage_derive proc. macros #637 (#711)

* [ink_storage] Add missing docs for ink_storage_derive. (paritytech/ink#637).

* Update crates/storage/derive/src/lib.rs

Co-authored-by: Hero Bird <robbepop@web.de>

* Update crates/storage/derive/src/lib.rs

Co-authored-by: Hero Bird <robbepop@web.de>

* Update crates/storage/derive/src/lib.rs

Co-authored-by: Hero Bird <robbepop@web.de>

* Update crates/storage/derive/src/lib.rs

Co-authored-by: Hero Bird <robbepop@web.de>

* Fix fmt.

Co-authored-by: Hero Bird <robbepop@web.de>

crates/storage/derive/Cargo.toml

@@ -24,6 +24,8 @@ proc-macro2 = "1.0"
 synstructure = "0.12.4"
 
 [dev-dependencies]
+scale = { package = "parity-scale-codec", version = "2.0", default-features = false, features = ["derive", "full"] }
+ink_env = { version = "3.0.0-rc3", path = "../../env" }
 ink_primitives = { version = "3.0.0-rc3", path = "../../primitives" }
 ink_metadata = { version = "3.0.0-rc3", path = "../../metadata" }
 ink_storage = { version = "3.0.0-rc3", path = ".." }

crates/storage/derive/src/lib.rs

@@ -12,6 +12,42 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+//! Custom derive for `ink_storage` traits.
+//!
+//! This crate provides helpers to define your very own custom storage data
+//! structures that work along the `ink_storage` data structures by implementing
+//! `SpreadLayout` and `PackedLayout` traits.
+//!
+//! See [Spread vs. Packed](https://paritytech.github.io/ink-docs/datastructures/spread-packed-layout)
+//! for more details of these two root strategies.
+//!
+//! # Examples
+//!
+//! ```no_run
+//! use ink_storage::traits::{SpreadLayout, push_spread_root};
+//! use ink_primitives::Key;
+//!
+//! # ink_env::test::run_test::<ink_env::DefaultEnvironment, _>(|_| {
+//! // Enum
+//! #[derive(SpreadLayout)]
+//! enum Vote {
+//!     Yes,
+//!     No
+//! }
+//!
+//! // Strucut
+//! #[derive(SpreadLayout)]
+//! struct NamedFields {
+//!     a: u32,
+//!     b: [u32; 32],
+//! };
+//!
+//! // Created a custom structure and told which key to update.
+//! push_spread_root(&NamedFields{ a: 123, b: [22; 32] }, &mut Key::from([0x42; 32]));
+//! # Ok(())
+//! # });
+//! ```
+
 extern crate proc_macro;
 
 mod packed_layout;
@@ -26,6 +62,113 @@ use self::{
     spread_layout::spread_layout_derive,
     storage_layout::storage_layout_derive,
 };
-synstructure::decl_derive!([SpreadLayout] => spread_layout_derive);
-synstructure::decl_derive!([PackedLayout] => packed_layout_derive);
-synstructure::decl_derive!([StorageLayout] => storage_layout_derive);
+synstructure::decl_derive!(
+    [SpreadLayout] =>
+    /// Derives `ink_storage`'s `SpreadLayout` trait for the given `struct` or `enum`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use ink_primitives::Key;
+    /// use ink_storage::traits::{
+    ///     SpreadLayout,
+    ///     push_spread_root,
+    ///     pull_spread_root,
+    ///};
+    ///
+    /// # ink_env::test::run_test::<ink_env::DefaultEnvironment, _>(|_| {
+    /// #[derive(SpreadLayout)]
+    /// struct NamedFields {
+    ///     a: u32,
+    ///     b: [u32; 32],
+    /// }
+    ///
+    /// let value = NamedFields {
+    ///     a: 123,
+    ///     b: [22; 32],
+    /// };
+    ///
+    /// push_spread_root(&value, &mut Key::from([0x42; 32]));
+    /// let value2: NamedFields = pull_spread_root(&mut Key::from([0x42; 32]));
+    /// assert_eq!(value.a, value2.a);
+    /// # Ok(())
+    /// # });
+    /// ```
+    spread_layout_derive
+);
+synstructure::decl_derive!(
+    [PackedLayout] =>
+    /// Derives `ink_storage`'s `PackedLayout` trait for the given `struct` or `enum`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use scale::{Encode, Decode};
+    /// use ink_primitives::Key;
+    /// use ink_storage::traits::{
+    ///     SpreadLayout,
+    ///     PackedLayout,
+    ///     push_packed_root,
+    ///     pull_packed_root
+    /// };
+    ///
+    /// # ink_env::test::run_test::<ink_env::DefaultEnvironment, _>(|_| {
+    /// #[derive(Encode, Decode, SpreadLayout, PackedLayout)]
+    /// struct NamedFields {
+    ///     a: u32,
+    ///     b: [u32; 32],
+    /// }
+    ///
+    /// let mut value = NamedFields {
+    ///     a: 123,
+    ///     b: [22; 32],
+    /// };
+    ///
+    /// push_packed_root(&value, &mut Key::from([0x42; 32]));
+    /// let value2: NamedFields = pull_packed_root(&mut Key::from([0x42; 32]));
+    /// assert_eq!(value.a, value2.a);
+    /// # Ok(())
+    /// # });
+    /// ```
+    packed_layout_derive
+);
+synstructure::decl_derive!(
+    [StorageLayout] =>
+    /// Derives `ink_storage`'s `StorageLayout` trait for the given `struct` or `enum`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use ink_metadata::layout::Layout::Struct;
+    /// use ink_primitives::Key;
+    /// use ink_storage::traits::{
+    ///     SpreadLayout,
+    ///     StorageLayout,
+    ///     push_spread_root,
+    ///     KeyPtr,
+    /// };
+    ///
+    /// # ink_env::test::run_test::<ink_env::DefaultEnvironment, _>(|_| {
+    /// #[derive(SpreadLayout, StorageLayout)]
+    /// struct NamedFields {
+    ///     a: u32,
+    ///     b: [u32; 32],
+    /// }
+    ///
+    /// let mut key = Key::from([0x42; 32]);
+    /// let mut value = NamedFields {
+    ///     a: 123,
+    ///     b: [22; 32],
+    /// };
+    ///
+    /// push_spread_root(&value, &key);
+    ///
+    /// if let Struct(layout) = <NamedFields as StorageLayout>::layout(&mut KeyPtr::from(key)) {
+    ///     assert_eq!(*layout.fields()[0].name().unwrap(), "a");
+    ///     assert_eq!(*layout.fields()[1].name().unwrap(), "b");
+    /// }
+    /// # Ok(())
+    /// # });
+    /// ```
+    storage_layout_derive
+);