Improve documentation of ink_storage::Mapping (#1138)

crates/storage/Cargo.toml

@@ -33,6 +33,8 @@ quickcheck_macros = "1.0"
 itertools = "0.10"
 paste = "1.0"
 
+ink_lang = { version = "3.0.0-rc8", path = "../lang/", default-features = false }
+
 [features]
 default = ["std"]
 std = [

crates/storage/src/lazy/mapping.rs

@@ -37,6 +37,54 @@ use ink_env::hash::{
 use ink_primitives::Key;
 
 /// A mapping of key-value pairs directly into contract storage.
+///
+/// # Important
+///
+/// If you use this data structure you must use the function
+/// [`ink_lang::utils::initialize_contract`](https://paritytech.github.io/ink/ink_lang/utils/fn.initialize_contract.html)
+/// in your contract's constructors!
+///
+/// Note that in order to use this function your contract's storage struct must implement the
+/// [`SpreadAllocate`](crate::traits::SpreadAllocate) trait.
+///
+/// This is an example of how you can do this:
+/// ```rust
+/// # use ink_lang as ink;
+/// # use ink_env::{
+/// #     Environment,
+/// #     DefaultEnvironment,
+/// # };
+/// # type AccountId = <DefaultEnvironment as Environment>::AccountId;
+///
+/// # #[ink::contract]
+/// # mod my_module {
+/// use ink_storage::{traits::SpreadAllocate, Mapping};
+///
+/// #[ink(storage)]
+/// #[derive(SpreadAllocate)]
+/// pub struct MyContract {
+///     balances: Mapping<AccountId, Balance>,
+/// }
+///
+/// impl MyContract {
+///     #[ink(constructor)]
+///     pub fn new() -> Self {
+///         ink_lang::utils::initialize_contract(Self::new_init)
+///     }
+///
+///     /// Default initializes the contract.
+///     fn new_init(&mut self) {
+///         let caller = Self::env().caller();
+///         let value: Balance = Default::default();
+///         self.balances.insert(&caller, &value);
+///     }
+/// #   #[ink(message)]
+/// #   pub fn my_message(&self) { }
+/// }
+/// # }
+/// ```
+///
+/// More usage examples can be found [in the ink! examples](https://github.com/paritytech/ink/tree/master/examples).
 #[cfg_attr(feature = "std", derive(scale_info::TypeInfo))]
 pub struct Mapping<K, V> {
     offset_key: Key,