diff --git a/substrate/srml/support/procedural/src/lib.rs b/substrate/srml/support/procedural/src/lib.rs index 342745efde..5db5c0bf60 100644 --- a/substrate/srml/support/procedural/src/lib.rs +++ b/substrate/srml/support/procedural/src/lib.rs @@ -41,64 +41,76 @@ use proc_macro::TokenStream; /// ``` /// /// Declaration is set with this header `(pub) trait Store for Module as Example` -/// with `Store` a (pub) trait generated associating each storage to the Module and -/// `as Example` setting the prefix used for storages of this module, it must be unique, -/// another module with same name and same inner storage name will conflict. +/// with `Store` a (pub) trait generated associating each storage to the `Module` and +/// `as Example` setting the prefix used for storages of this module. `Example` must be unique: +/// another module with same name and same inner storage item name will conflict. /// -/// Basic storage consist of a name and a type, supported types are: -/// * storage value: `Foo: type`: implements [StorageValue](https://crates.parity.io/srml_support/storage/trait.StorageValue.html) -/// * storage map: `Foo: map type => type`: implements [StorageMap](https://crates.parity.io/srml_support/storage/trait.StorageMap.html) -/// * storage linked map: `Foo: linked_map type => type`: implements [StorageMap](https://crates.parity.io/srml_support/storage/trait.StorageMap.html) and [EnumarableStorageMap](https://crates.parity.io/srml_support/storage/trait.EnumerableStorageMap.html) -/// * storage double map: Foo: double_map u32, $hash(u32) => u32;` implements `StorageDoubleMap` with hasher $hash one available in `Hashable` trait -/// /!\ be careful while choosing the Hash, indeed malicious could craft second keys to lower the trie. +/// Basic storage consists of a name and a type; supported types are: +/// +/// * Value: `Foo: type`: Implements [StorageValue](../srml_support/storage/trait.StorageValue.html). +/// * Map: `Foo: map type => type`: implements [StorageMap](../srml_support/storage/trait.StorageMap.html) +/// * Linked map: `Foo: linked_map type => type`: Implements [StorageMap](../srml_support/storage/trait.StorageMap.html) +/// and [EnumarableStorageMap](../srml_support/storage/trait.EnumerableStorageMap.html). +/// * Double map: `Foo: double_map u32, $hash(u32) => u32;`: Implements `StorageDoubleMap` with `$hash` representing a +/// choice of hashing algorithms available in [`Hashable` trait](../srml_support/trait.Hashable.html). +/// +/// /!\ Be careful when choosing the hash function, malicious actors could craft second keys to lower the trie. /// /// And it can be extended as such: /// /// `#vis #name get(#getter) config(#field_name) build(#closure): #type = #default;` -/// * `#vis`: set the visibility of the structure -/// * `#name`: name of the storage, used as a prefix in the storage -/// * [optional] `get(#getter)`: implements the function #getter to `Module` -/// * [optional] `config(#field_name)`: `field_name` is optional if get is set: include in `GenesisConfig` -/// * [optional] `build(#closure)`: closure called with storage overlays -/// * `#type`: storage type -/// * [optional] `#default`: value returned when none /// -/// Storages are accessible in multiples ways, using: -/// * the structure: `Foo::` -/// * the `Store` trait structure: ` as Store>::Foo` -/// * the getter on the module which calls get on the structure: `Module::::foo()` +/// * `#vis`: Set the visibility of the structure. `pub` or nothing. +/// * `#name`: Name of the storage item, used as a prefix in storage. +/// * [optional] `get(#getter)`: Implements the function #getter to `Module`. +/// * [optional] `config(#field_name)`: `field_name` is optional if get is set. +/// Will include the item in `GenesisConfig`. +/// * [optional] `build(#closure)`: Closure called with storage overlays. +/// * `#type`: Storage type. +/// * [optional] `#default`: Value returned when none. +/// +/// Storage items are accessible in multiple ways: +/// +/// * The structure: `Foo::` +/// * The `Store` trait structure: ` as Store>::Foo` +/// * The getter on the module that calls get on the structure: `Module::::foo()` /// /// ## GenesisConfig /// /// An optional `GenesisConfig` struct for storage initialization can be defined, either /// when at least one storage field requires default initialization -/// (both `get` and `config` or `build`), or specifically as in : +/// (both `get` and `config` or `build`), or specifically as in: +/// /// ```nocompile /// decl_storage! { /// trait Store for Module as Example { +/// +/// // Your storage items /// } /// add_extra_genesis { /// config(genesis_field): GenesisFieldType; /// config(genesis_field2): GenesisFieldType; /// ... /// build(|_: &mut StorageOverlay, _: &mut ChildrenStorageOverlay, _: &GenesisConfig| { -/// // Modification of storages +/// // Modification of storage /// }) /// } /// } /// ``` -/// This struct can be expose as `Config` by `decl_runtime` macro. +/// +/// This struct can be exposed as `Config` by the `decl_runtime!` macro. /// /// ### Module with instances /// -/// `decl_storage!` macro support building modules with instances with the following syntax: (DefaultInstance type -/// is optional) +/// The `decl_storage!` macro supports building modules with instances with the following syntax: +/// (`DefaultInstance` type is optional) +/// /// ```nocompile /// trait Store for Module, I: Instance=DefaultInstance> as Example {} /// ``` /// /// Then the genesis config is generated with two generic parameter `GenesisConfig` -/// and storages are now accessible using two generic parameters like: +/// and storage items are now accessible using two generic parameters, e.g.: /// `>::get()` or `Dummy::::get()` #[proc_macro] pub fn decl_storage(input: TokenStream) -> TokenStream { diff --git a/substrate/srml/support/src/hashable.rs b/substrate/srml/support/src/hashable.rs index 886c88b23a..9199a0958d 100644 --- a/substrate/srml/support/src/hashable.rs +++ b/substrate/srml/support/src/hashable.rs @@ -19,6 +19,7 @@ use crate::codec::Codec; use runtime_io::{blake2_256, twox_128, twox_256}; +/// Trait for available hash functions. pub trait Hashable: Sized { fn blake2_256(&self) -> [u8; 32]; fn twox_128(&self) -> [u8; 16];