Update Externalities docs (#5537)

* update externalities docs

* Update primitives/externalities/src/lib.rs

Co-Authored-By: Bastian Köcher <bkchr@users.noreply.github.com>

* Update primitives/externalities/src/lib.rs

Co-Authored-By: Bastian Köcher <bkchr@users.noreply.github.com>

* Update primitives/externalities/src/lib.rs

Co-Authored-By: Bastian Köcher <bkchr@users.noreply.github.com>

* Update primitives/externalities/src/lib.rs

Co-Authored-By: Bastian Köcher <bkchr@users.noreply.github.com>

Co-authored-by: Bastian Köcher <bkchr@users.noreply.github.com>

primitives/externalities/src/lib.rs

@@ -39,10 +39,14 @@ pub trait Externalities: ExtensionStore {
 	/// Read runtime storage.
 	fn storage(&self, key: &[u8]) -> Option<Vec<u8>>;
 
-	/// Get storage value hash. This may be optimized for large values.
+	/// Get storage value hash.
+	///
+	/// This may be optimized for large values.
 	fn storage_hash(&self, key: &[u8]) -> Option<Vec<u8>>;
 
-	/// Get child storage value hash. This may be optimized for large values.
+	/// Get child storage value hash.
+	///
+	/// This may be optimized for large values.
 	///
 	/// Returns an `Option` that holds the SCALE encoded hash.
 	fn child_storage_hash(
@@ -136,7 +140,7 @@ pub trait Externalities: ExtensionStore {
 	/// Set or clear a storage entry (`key`) of current contract being called (effective immediately).
 	fn place_storage(&mut self, key: Vec<u8>, value: Option<Vec<u8>>);
 
-	/// Set or clear a child storage entry. Return whether the operation succeeds.
+	/// Set or clear a child storage entry.
 	fn place_child_storage(
 		&mut self,
 		storage_key: ChildStorageKey,
@@ -148,29 +152,29 @@ pub trait Externalities: ExtensionStore {
 	/// Get the identity of the chain.
 	fn chain_id(&self) -> u64;
 
-	/// Get the trie root of the current storage map. This will also update all child storage keys
-	/// in the top-level storage map.
+	/// Get the trie root of the current storage map.
 	///
-	/// The hash is defined by the `Block`.
+	/// This will also update all child storage keys in the top-level storage map.
 	///
-	/// Returns the SCALE encoded hash.
+	/// The returned hash is defined by the `Block` and is SCALE encoded.
 	fn storage_root(&mut self) -> Vec<u8>;
 
-	/// Get the trie root of a child storage map. This will also update the value of the child
-	/// storage keys in the top-level storage map.
+	/// Get the trie root of a child storage map.
+	///
+	/// This will also update the value of the child storage keys in the top-level storage map.
+	///
 	/// If the storage root equals the default hash as defined by the trie, the key in the top-level
 	/// storage map will be removed.
 	fn child_storage_root(
 		&mut self,
 		storage_key: ChildStorageKey,
 	) -> Vec<u8>;
 
-	/// Get the change trie root of the current storage overlay at a block with given parent.
-	/// `parent` is expects a SCALE encoded hash.
+	/// Get the changes trie root of the current storage overlay at a block with given `parent`.
 	///
-	/// The hash is defined by the `Block`.
+	/// `parent` expects a SCALE encoded hash.
 	///
-	/// Returns the SCALE encoded hash.
+	/// The returned hash is defined by the `Block` and is SCALE encoded.
 	fn storage_changes_root(&mut self, parent: &[u8]) -> Result<Option<Vec<u8>>, ()>;
 
 	/// !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!