Unverified Commit b66730ba authored by Hsin Yi, Chen's avatar Hsin Yi, Chen Committed by GitHub
Browse files

[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's avatarHero Bird <robbepop@web.de>

* Update crates/storage/derive/src/lib.rs
Co-authored-by: Hero Bird's avatarHero Bird <robbepop@web.de>

* Update crates/storage/derive/src/lib.rs
Co-authored-by: Hero Bird's avatarHero Bird <robbepop@web.de>

* Update crates/storage/derive/src/lib.rs
Co-authored-by: Hero Bird's avatarHero Bird <robbepop@web.de>

* Fix fmt.
Co-authored-by: Hero Bird's avatarHero Bird <robbepop@web.de>
parent ac501b24
Pipeline #126933 failed with stages
in 7 minutes and 44 seconds
......@@ -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 = ".." }
......@@ -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
);
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment