diff --git a/substrate/srml/support/procedural/src/lib.rs b/substrate/srml/support/procedural/src/lib.rs
index 5db5c0bf60..aab39224c2 100644
--- a/substrate/srml/support/procedural/src/lib.rs
+++ b/substrate/srml/support/procedural/src/lib.rs
@@ -40,23 +40,47 @@ 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. `Example` must be unique:
-/// another module with same name and same inner storage item name will conflict.
+/// Declaration is set with the header `(pub) trait Store for Module<T: Trait> as Example`,
+/// with `Store` a (pub) trait generated associating each storage item to the `Module` and
+/// `as Example` setting the prefix used for storage items of this module. `Example` must be unique:
+/// another module with the same name and the same inner storage item name will conflict.
 ///
 /// 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).
+/// * Map: `Foo: map hasher($hash) type => type`: Implements [StorageMap](../srml_support/storage/trait.StorageMap.html)
+///   with `$hash` representing a choice of hashing algorithms available in the
+///   [`Hashable` trait](../srml_support/trait.Hashable.html).
 ///
-///   /!\ Be careful when choosing the hash function, malicious actors could craft second keys to lower the trie.
+///   `hasher($hash)` is optional and its default is `blake2_256`.
 ///
-/// And it can be extended as such:
+///   /!\ Be careful with each key in the map that is inserted in the trie `$hash(module_name ++ storage_name ++ key)`.
+///   If the keys are not trusted (e.g. can be set by a user), a cryptographic `hasher` such as
+///   `blake2_256` must be used. Otherwise, other values in storage can be compromised.
+///
+/// * Linked map: `Foo: linked_map hasher($hash) type => type`: Same as `Map` but also implements
+///   [EnumarableStorageMap](../srml_support/storage/trait.EnumerableStorageMap.html).
+///
+/// * Double map: `Foo: double_map hasher($hash) u32, $hash2(u32) => u32`: Implements `StorageDoubleMap` with
+///   `$hash` and `$hash2` representing choices of hashing algorithms available in the
+///   [`Hashable` trait](../srml_support/trait.Hashable.html).
+///
+///   `hasher($hash)` is optional and its default is `blake2_256`.
+///
+///   /!\ Be careful with each key pair in the double map that is inserted in the trie.
+///   The final key is calculated as follows:
+///
+///   ```nocompile
+///   $hash(module_name ++ storage_name ++ first_key) ++ $hash2(second_key)
+///   ```
+///
+///   If the first key is untrusted, a cryptographic `hasher` such as `blake2_256` must be used.
+///   Otherwise, other values of all storage items can be compromised.
+///
+///   If the second key is untrusted, a cryptographic `hasher` such as `blake2_256` must be used.
+///   Otherwise, other items in storage with the same first key can be compromised.
+///
+/// Basic storage can be extended as such:
 ///
 /// `#vis #name get(#getter) config(#field_name) build(#closure): #type = #default;`
 ///
@@ -100,18 +124,18 @@ use proc_macro::TokenStream;
 ///
 /// This struct can be exposed as `Config` by the `decl_runtime!` macro.
 ///
-/// ### Module with instances
+/// ### Module with Instances
 ///
-/// The `decl_storage!` macro supports 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 storage items are now accessible using two generic parameters, e.g.:
-/// `<Dummy<T, I>>::get()` or `Dummy::<T, I>::get()`
+/// Then the genesis config is generated with two generic parameters (i.e. `GenesisConfig<T, I>`)
+/// and storage items are 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 {
 	storage::transformation::decl_storage_impl(input)