Reflect all possible Mapping failure cases in comments (#2079)

* Add missing changelog entries

* Reflect all possible failure cases in comments

* Make changelog consistent

* Add changelog entry

* Apply Cyrill's remarks

CHANGELOG.md

@@ -6,10 +6,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+- `Mapping`: Reflect all possible failure cases in comments ‒ [#2079](https://github.com/paritytech/ink/pull/2079)
+
 ### Added
 - Custom signature topic in Events - [#2031](https://github.com/paritytech/ink/pull/2031)
-- Linter: `non_fallible_api` lint - [#2004](https://github.com/paritytech/ink/pull/2004)
-- Linter: Publish the linting crates on crates.io - [#2060](https://github.com/paritytech/ink/pull/2060)
+- [Linter] `non_fallible_api` lint - [#2004](https://github.com/paritytech/ink/pull/2004)
+- [Linter] Publish the linting crates on crates.io - [#2060](https://github.com/paritytech/ink/pull/2060)
 - [E2E] Added `create_call_builder` for testing existing contracts - [#2075](https://github.com/paritytech/ink/pull/2075)
 
 ### Changed
@@ -25,6 +28,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Clean E2E configuration parsing - [#1922](https://github.com/paritytech/ink/pull/1922)
 - Make `set_code_hash` generic - [#1906](https://github.com/paritytech/ink/pull/1906)
 - Provide a `StorageVec` datastructure built on top of `Lazy` - [#1995](https://github.com/paritytech/ink/pull/1995)
+- Add fallible methods for `Mapping` and `Lazy` - [#1910](https://github.com/paritytech/ink/pull/1910)
 - [E2E] Allow testing with live-chain state - [#1949](https://github.com/paritytech/ink/pull/1949)
 - [E2E] Call builders and extra gas margin option - [#1917](https://github.com/paritytech/ink/pull/1917)
 - [Linter] `storage_never_freed` lint - [#1932](https://github.com/paritytech/ink/pull/1932)

crates/storage/src/lazy/mapping.rs

@@ -138,7 +138,8 @@ where
     ///
     /// # Panics
     ///
-    /// Traps if the encoded `value` doesn't fit into the static buffer.
+    /// Traps if encoding the `key` together with the `value` doesn't fit into the static
+    /// buffer.
     #[inline]
     pub fn insert<Q, R>(&mut self, key: Q, value: &R) -> Option<u32>
     where
@@ -150,13 +151,14 @@ where
 
     /// Try to insert the given `value` into the mapping under given `key`.
     ///
-    /// Fails if `value` exceeds the static buffer size.
+    /// Fails if `key` or `value` exceeds the static buffer size.
     ///
     /// Returns:
     /// - `Ok(Some(_))` if the value was inserted successfully, containing the size in
     ///   bytes of the pre-existing value at the specified key if any.
     /// - `Ok(None)` if the insert was successful but there was no pre-existing value.
-    /// - `Err(_)` if the encoded value exceeds the static buffer size.
+    /// - `Err(_)` if encoding the `key` together with the `value` exceeds the static
+    ///   buffer size.
     #[inline]
     pub fn try_insert<Q, R>(&mut self, key: Q, value: &R) -> ink_env::Result<Option<u32>>
     where
@@ -184,7 +186,7 @@ where
     ///
     /// # Panics
     ///
-    /// Traps if the encoded `value` doesn't fit into the static buffer.
+    /// Traps if the the encoded `key` or `value` doesn't fit into the static buffer.
     #[inline]
     pub fn get<Q>(&self, key: Q) -> Option<V>
     where
@@ -198,8 +200,8 @@ where
     ///
     /// Returns:
     /// - `Some(Ok(_))` containing the value if it existed and was decoded successfully.
-    /// - `Some(Err(_))` if the value existed but its length exceeds the static buffer
-    ///   size.
+    /// - `Some(Err(_))` if either (a) the encoded key doesn't fit into the static buffer
+    ///   or (b) the value existed but its length exceeds the static buffer size.
     /// - `None` if there was no value under this mapping key.
     #[inline]
     pub fn try_get<Q>(&self, key: Q) -> Option<ink_env::Result<V>>
@@ -231,7 +233,7 @@ where
     ///
     /// # Panics
     ///
-    /// Traps if the encoded `value` doesn't fit into the static buffer.
+    /// Traps if the encoded `key` or `value` doesn't fit into the static buffer.
     ///
     /// # Warning
     ///
@@ -252,8 +254,8 @@ where
     ///
     /// Returns:
     /// - `Some(Ok(_))` containing the value if it existed and was decoded successfully.
-    /// - `Some(Err(_))` if the value existed but its length exceeds the static buffer
-    ///   size.
+    /// - `Some(Err(_))` if either (a) the encoded key doesn't fit into the static buffer
+    ///   or (b) the value existed but its length exceeds the static buffer size.
     /// - `None` if there was no value under this mapping key.
     ////
     /// # Warning