Improve storage doc (#3691)

* doc

* fix

* Apply suggestions from code review

Co-Authored-By: Kian Paimani <5588131+kianenigma@users.noreply.github.com>

* complete suggestion

substrate/srml/support/src/storage/generator/double_map.rs

@@ -26,10 +26,18 @@ use crate::{storage::{self, unhashed, hashed::StorageHasher}, rstd::borrow::Borr
 /// The first part is a hash of a concatenation of the `key1_prefix` and `Key1`. And the second part
 /// is a hash of a `Key2`.
 ///
-/// Thus value for (key1, key2) is stored at `Hasher1(key1_prefix ++ key1) ++ Hasher2(key2)`.
+/// Thus value for (key1, key2) is stored at:
+/// ```nocompile
+/// Hasher1(key1_prefix ++ key1) ++ Hasher2(key2)
+/// ```
 ///
-/// /!\ be careful while choosing the Hash, indeed malicious could craft second keys to lower the
-/// trie.
+/// # Warning
+///
+/// If the key1s are not trusted (e.g. can be set by a user), a cryptographic `hasher` such as
+/// `blake2_256` must be used for Hasher1. Otherwise, other values in storage can be compromised.
+/// If the key2s are not trusted (e.g. can be set by a user), a cryptographic `hasher` such as
+/// `blake2_256` must be used for Hasher2. Otherwise, other items in storage with the same first
+/// key can be compromised.
 pub trait StorageDoubleMap<K1: Encode, K2: Encode, V: Codec> {
 	/// The type that get/take returns.
 	type Query;

substrate/srml/support/src/storage/generator/linked_map.rs

@@ -23,8 +23,26 @@ use rstd::{
 
 /// Generator for `StorageLinkedMap` used by `decl_storage`.
 ///
-/// For each key value is stored at `Hasher(prefix ++ key)` along with a linkage used for
-/// enumeration.
+/// # Mapping of keys to a storage path
+///
+/// The key for the head of the map is stored at one fixed path:
+/// ```nocompile
+/// Hasher(head_key)
+/// ```
+///
+/// For each key, the value stored under that key is appended with a
+/// [`Linkage`](struct.Linkage.html) (which hold previous and next key) at the path:
+/// ```nocompile
+/// Hasher(prefix ++ key)
+/// ```
+///
+/// Enumeration is done by getting the head of the linked map and then iterating getting the
+/// value and linkage stored at the key until the found linkage has no next key.
+///
+/// # Warning
+///
+/// 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.
 pub trait StorageLinkedMap<K: Codec, V: Codec> {
 	/// The type that get/take returns.
 	type Query;

substrate/srml/support/src/storage/generator/map.rs

@@ -22,7 +22,15 @@ use crate::{storage::{self, unhashed, hashed::StorageHasher}, traits::Len};
 
 /// Generator for `StorageMap` used by `decl_storage`.
 ///
-/// For each key value is stored at `Hasher(prefix ++ key)`.
+/// For each key value is stored at:
+/// ```nocompile
+/// Hasher(prefix ++ key)
+/// ```
+///
+/// # Warning
+///
+/// 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.
 pub trait StorageMap<K: Codec, V: Codec> {
 	/// The type that get/take returns.
 	type Query;

substrate/srml/support/src/storage/generator/value.rs

@@ -22,7 +22,10 @@ use crate::{storage::{self, unhashed, hashed::{Twox128, StorageHasher}}, traits:
 
 /// Generator for `StorageValue` used by `decl_storage`.
 ///
-/// Value is stored at `Twox128(unhashed_key)`.
+/// Value is stored at:
+/// ```nocompile
+/// Twox128(unhashed_key)
+/// ```
 pub trait StorageValue<T: Codec> {
 	/// The type that get/take returns.
 	type Query;