Update docs for the wasm executor crate (#3569)

* Grammar.

* Update docs for wasm executor.

* Update core/executor/src/lib.rs

Co-Authored-By: André Silva <andre.beat@gmail.com>

substrate/core/executor/src/lib.rs

@@ -14,16 +14,17 @@
 // You should have received a copy of the GNU General Public License
 // along with Substrate.  If not, see <http://www.gnu.org/licenses/>.
 
-//! Temporary crate for contracts implementations.
+//! A crate that provides means of executing/dispatching calls into the runtime.
 //!
-//! This will be replaced with WASM contracts stored on-chain.
-//! ** NOTE ***
-//! This is entirely deprecated with the idea of a single-module Wasm module for state transition.
-//! The dispatch table should be replaced with the specific functions needed:
-//! - execute_block(bytes)
-//! - init_block(PrevBlock?) -> InProgressBlock
-//! - add_transaction(InProgressBlock) -> InProgressBlock
-//! It is left as is for now as it might be removed before this is ever done.
+//! There are a few responsibilities of this crate at the moment:
+//!
+//! - It provides an implementation of a common entrypoint for calling into the runtime, both
+//! wasm and compiled.
+//! - It defines the environment for the wasm execution, namely the host functions that are to be
+//! provided into the wasm runtime module.
+//! - It also provides the required infrastructure for executing the current wasm runtime (specified
+//! by the current value of `:code` in the provided externalities), i.e. interfacing with
+//! wasm engine used, instance cache.
 
 #![warn(missing_docs)]
 #![recursion_limit="128"]

substrate/core/executor/src/native_executor.rs

@@ -47,9 +47,13 @@ pub fn with_native_environment<F, U>(ext: &mut dyn Externalities<Blake2Hasher>,
 	::runtime_io::with_externalities(ext, move || safe_call(f))
 }
 
-/// Delegate for dispatching a CodeExecutor call to native code.
+/// Delegate for dispatching a CodeExecutor call.
+///
+/// By dispatching we mean that we execute a runtime function specified by it's name.
 pub trait NativeExecutionDispatch: Send + Sync {
-	/// Dispatch a method and input data to be executed natively.
+	/// Dispatch a method in the runtime.
+	///
+	/// If the method with the specified name doesn't exist then `Err` is returned.
 	fn dispatch(ext: &mut dyn Externalities<Blake2Hasher>, method: &str, data: &[u8]) -> Result<Vec<u8>>;
 
 	/// Provide native runtime version.

substrate/core/executor/src/wasm_executor.rs

@@ -14,7 +14,10 @@
 // You should have received a copy of the GNU General Public License
 // along with Substrate.  If not, see <http://www.gnu.org/licenses/>.
 
-//! Rust implementation of Substrate contracts.
+//! Wasm interface module.
+//!
+//! This module defines and implements the wasm part of Substrate Host Interface and provides
+//! an interface for calling into the wasm runtime.
 
 use std::{collections::HashMap, convert::TryFrom, str};
 use tiny_keccak;

substrate/core/executor/src/wasm_utils.rs

@@ -14,7 +14,7 @@
 // You should have received a copy of the GNU General Public License
 // along with Substrate.  If not, see <http://www.gnu.org/licenses/>.
 
-//! Rust implementation of Substrate contracts.
+//! Utilities for defining the wasm host environment.
 
 use wasmi::{ValueType, RuntimeValue};
 use wasmi::nan_preserving_float::{F32, F64};

substrate/core/state-machine/src/lib.rs

@@ -226,10 +226,10 @@ pub trait Externalities<H: Hasher> {
 	/// Clear an entire child storage.
 	fn kill_child_storage(&mut self, storage_key: ChildStorageKey<H>);
 
-	/// Clear storage entries which keys are start with the given prefix.
+	/// Clear storage entries which keys start with the given prefix.
 	fn clear_prefix(&mut self, prefix: &[u8]);
 
-	/// Clear child storage entries which keys are start with the given prefix.
+	/// Clear child storage entries which keys start with the given prefix.
 	fn clear_child_prefix(&mut self, storage_key: ChildStorageKey<H>, prefix: &[u8]);
 
 	/// Set or clear a storage entry (`key`) of current contract being called (effective immediately).