decl_storage doc (#2341)

* doc

* other doc cleanup and fixing links

* one more typo

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<T: Trait> 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::<T>`
-/// * the `Store` trait structure: `<Module<T> as Store>::Foo`
-/// * the getter on the module which calls get on the structure: `Module::<T>::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::<T>`
+/// * The `Store` trait structure: `<Module<T> as Store>::Foo`
+/// * The getter on the module that calls get on the structure: `Module::<T>::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<T: Trait> as Example {
+///
+/// 		// Your storage items
 /// 	}
 ///		add_extra_genesis {
 ///			config(genesis_field): GenesisFieldType;
 ///			config(genesis_field2): GenesisFieldType;
 ///			...
 ///			build(|_: &mut StorageOverlay, _: &mut ChildrenStorageOverlay, _: &GenesisConfig<T>| {
-///				// 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<T: Trait<I>, I: Instance=DefaultInstance> as Example {}
 /// ```
 ///
 /// Then the genesis config is generated with two generic parameter `GenesisConfig<T, I>`
-/// and storages are now accessible using two generic parameters like:
+/// and storage items are now accessible using two generic parameters, e.g.:
 /// `<Dummy<T, I>>::get()` or `Dummy::<T, I>::get()`
 #[proc_macro]
 pub fn decl_storage(input: TokenStream) -> TokenStream {

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];