[contracts] Add docs generator for the contracts API to the #[define_env] macro (#13032)

* macro to expand traits for host functions documentation

* other way: same Doc trait in seal modules

* added docs for macro, and remove `doc` attribute

* fmt

* Apply suggestions from code review

Co-authored-by: Alexander Theißen <alex.theissen@me.com>

* make docs to be generated into re-exported `api_doc` module; fix
unrelated elder docs;

* make it compile without `doc` attr passed to macro

* make alias functions indicated explicitly in docs

* tidy up docs

* refactored a bit

* macro to auto-add doc warning for unstable functions

* invoke macro with no doc generation by default

* addressed review comments

* hide api_doc module behind cfg(doc)

Co-authored-by: Alexander Theißen <alex.theissen@me.com>

substrate/frame/contracts/proc-macro/src/lib.rs

@@ -30,9 +30,12 @@ use alloc::{
 	vec::Vec,
 };
 use proc_macro::TokenStream;
-use proc_macro2::TokenStream as TokenStream2;
+use proc_macro2::{Span, TokenStream as TokenStream2};
 use quote::{quote, quote_spanned, ToTokens};
-use syn::{parse_macro_input, spanned::Spanned, Data, DeriveInput, FnArg, Ident};
+use syn::{
+	parse_macro_input, punctuated::Punctuated, spanned::Spanned, token::Comma, Data, DeriveInput,
+	FnArg, Ident,
+};
 
 /// This derives `Debug` for a struct where each field must be of some numeric type.
 /// It interprets each field as its represents some weight and formats it as times so that
@@ -158,6 +161,7 @@ struct HostFn {
 	name: String,
 	returns: HostFnReturn,
 	is_stable: bool,
+	alias_to: Option<String>,
 }
 
 enum HostFnReturn {
@@ -187,7 +191,7 @@ impl ToTokens for HostFn {
 }
 
 impl HostFn {
-	pub fn try_from(item: syn::ItemFn) -> syn::Result<Self> {
+	pub fn try_from(mut item: syn::ItemFn) -> syn::Result<Self> {
 		let err = |span, msg| {
 			let msg = format!("Invalid host function definition. {}", msg);
 			syn::Error::new(span, msg)
@@ -198,10 +202,10 @@ impl HostFn {
 			"only #[version(<u8>)], #[unstable] and #[prefixed_alias] attributes are allowed.";
 		let span = item.span();
 		let mut attrs = item.attrs.clone();
-		attrs.retain(|a| !(a.path.is_ident("doc") || a.path.is_ident("prefixed_alias")));
-		let name = item.sig.ident.to_string();
+		attrs.retain(|a| !a.path.is_ident("doc"));
 		let mut maybe_module = None;
 		let mut is_stable = true;
+		let mut alias_to = None;
 		while let Some(attr) = attrs.pop() {
 			let ident = attr.path.get_ident().ok_or(err(span, msg))?.to_string();
 			match ident.as_str() {
@@ -219,9 +223,17 @@ impl HostFn {
 					}
 					is_stable = false;
 				},
+				"prefixed_alias" => {
+					alias_to = Some(item.sig.ident.to_string());
+					item.sig.ident = syn::Ident::new(
+						&format!("seal_{}", &item.sig.ident.to_string()),
+						item.sig.ident.span(),
+					);
+				},
 				_ => return Err(err(span, msg)),
 			}
 		}
+		let name = item.sig.ident.to_string();
 
 		// process arguments: The first and second arg are treated differently (ctx, memory)
 		// they must exist and be `ctx: _` and `memory: _`.
@@ -317,6 +329,7 @@ impl HostFn {
 							name,
 							returns,
 							is_stable,
+							alias_to,
 						})
 					},
 					_ => Err(err(span, &msg)),
@@ -348,19 +361,15 @@ impl EnvDef {
 			.iter()
 			.filter_map(extract_fn)
 			.filter(|i| i.attrs.iter().any(selector))
-			.map(|mut i| {
-				i.attrs.retain(|i| !selector(i));
-				i.sig.ident = syn::Ident::new(
-					&format!("seal_{}", &i.sig.ident.to_string()),
-					i.sig.ident.span(),
-				);
-				i
-			})
 			.map(|i| HostFn::try_from(i));
 
 		let host_funcs = items
 			.iter()
 			.filter_map(extract_fn)
+			.map(|mut i| {
+				i.attrs.retain(|i| !selector(i));
+				i
+			})
 			.map(|i| HostFn::try_from(i))
 			.chain(aliases)
 			.collect::<Result<Vec<_>, _>>()?;
@@ -383,16 +392,111 @@ fn is_valid_special_arg(idx: usize, arg: &FnArg) -> bool {
 	matches!(*pat.ty, syn::Type::Infer(_))
 }
 
+/// Expands documentation for host functions.
+fn expand_docs(def: &mut EnvDef) -> TokenStream2 {
+	let mut modules = def.host_funcs.iter().map(|f| f.module.clone()).collect::<Vec<_>>();
+	modules.sort();
+	modules.dedup();
+
+	let doc_selector = |a: &syn::Attribute| a.path.is_ident("doc");
+	let docs = modules.iter().map(|m| {
+		let funcs = def.host_funcs.iter_mut().map(|f| {
+			if *m == f.module {
+				// Remove auxiliary args: `ctx: _` and `memory: _`
+				f.item.sig.inputs = f
+					.item
+					.sig
+					.inputs
+					.iter()
+					.skip(2)
+					.map(|p| p.clone())
+					.collect::<Punctuated<FnArg, Comma>>();
+				let func_decl = f.item.sig.to_token_stream();
+				let func_doc = if let Some(origin_fn) = &f.alias_to {
+					let alias_doc = format!(
+						"This is just an alias function to [`{0}()`][`Self::{0}`] with backwards-compatible prefixed identifier.",
+						origin_fn,
+					);
+					quote! { #[doc = #alias_doc] }
+
+				} else {
+					let func_docs = f.item.attrs.iter().filter(|a| doc_selector(a)).map(|d| {
+						let docs = d.to_token_stream();
+						quote! { #docs }
+					});
+					let unstable_notice = if !f.is_stable {
+						let warning = "\n # Unstable\n\n \
+									    This function is unstable and it is a subject to change (or removal) in the future.\n \
+									    Do not deploy a contract using it to a production chain.";
+						quote! { #[doc = #warning] }
+					} else {
+						quote! {}
+					};
+					quote! {
+						#( #func_docs )*
+						#unstable_notice
+					}
+				};
+				quote! {
+					#func_doc
+					#func_decl;
+				}
+			} else {
+				quote! {}
+			}
+		});
+
+		let module = Ident::new(m, Span::call_site());
+		let module_doc = format!(
+			"Documentation of the API available to contracts by importing `{}` WASM module.",
+			module
+		);
+
+		quote! {
+			#[doc = #module_doc]
+			pub mod #module {
+				use crate::wasm::runtime::{TrapReason, ReturnCode};
+				/// Every function in this trait represents (at least) one function that can be imported by a contract.
+				///
+				/// The function's identifier is to be set as the name in the import definition.
+				/// Where it is specifically indicated, an _alias_ function having `seal_`-prefixed identifier and
+				/// just the same signature and body, is also available (for backwards-compatibility purposes).
+				pub trait Api {
+					#( #funcs )*
+				}
+			}
+		}
+	});
+	quote! {
+		  #( #docs )*
+	}
+}
+
 /// Expands environment definiton.
 /// Should generate source code for:
 ///  - implementations of the host functions to be added to the wasm runtime environment (see
 ///    `expand_impls()`).
-fn expand_env(def: &mut EnvDef) -> TokenStream2 {
+fn expand_env(def: &mut EnvDef, docs: bool) -> TokenStream2 {
 	let impls = expand_impls(def);
+	let docs = docs.then_some(expand_docs(def)).unwrap_or(TokenStream2::new());
 
 	quote! {
 		pub struct Env;
 		#impls
+		/// Contains the documentation of the API available to contracts.
+		///
+		/// In order to generate this documentation, pass `doc` attribute to the [`#[define_env]`][`macro@define_env`] macro:
+		/// `#[define_env(doc)]`, and then run `cargo doc`.
+		///
+		/// This module is not meant to be used by any code. Rather, it is meant to be consumed by humans through rustdoc.
+		///
+		/// Every function described in this module's sub module's traits uses this sub module's identifier
+		/// as its imported module name. The identifier of the function is the function's imported name.
+		/// According to the [WASM spec of imports](https://webassembly.github.io/spec/core/text/modules.html#text-import).
+		#[cfg(doc)]
+		pub mod api_doc {
+			#docs
+		}
 	}
 }
 
@@ -579,10 +683,25 @@ fn expand_functions(
 ///
 /// The implementation on `()` can be used in places where no `Ext` exists, yet. This is useful
 /// when only checking whether a code can be instantiated without actually executing any code.
+///
+/// # Generating Documentation
+///
+/// Passing `doc` attribute to the macro (like `#[define_env(doc)]`) will make it also expand
+/// additional `pallet_contracts::api_doc::seal0`, `pallet_contracts::api_doc::seal1`,
+/// `...` modules each having its `Api` trait containing functions holding documentation for every
+/// host function defined by the macro.
+///
+/// To build up these docs, run:
+///
+/// ```nocompile
+/// cargo doc
+/// ```
 #[proc_macro_attribute]
 pub fn define_env(attr: TokenStream, item: TokenStream) -> TokenStream {
-	if !attr.is_empty() {
-		let msg = "Invalid `define_env` attribute macro: expected no attributes: `#[define_env]`.";
+	if !attr.is_empty() && !(attr.to_string() == "doc".to_string()) {
+		let msg = r#"Invalid `define_env` attribute macro: expected either no attributes or a single `doc` attibute:
+					 - `#[define_env]`
+					 - `#[define_env(doc)]`"#;
 		let span = TokenStream2::from(attr).span();
 		return syn::Error::new(span, msg).to_compile_error().into()
 	}
@@ -590,7 +709,7 @@ pub fn define_env(attr: TokenStream, item: TokenStream) -> TokenStream {
 	let item = syn::parse_macro_input!(item as syn::ItemMod);
 
 	match EnvDef::try_from(item) {
-		Ok(mut def) => expand_env(&mut def).into(),
+		Ok(mut def) => expand_env(&mut def, !attr.is_empty()).into(),
 		Err(e) => e.to_compile_error().into(),
 	}
 }

substrate/frame/contracts/src/exec.rs

@@ -462,7 +462,7 @@ enum FrameArgs<'a, T: Config, E> {
 		/// If `None` the contract info needs to be reloaded from storage.
 		cached_info: Option<ContractInfo<T>>,
 		/// This frame was created by `seal_delegate_call` and hence uses different code than
-		/// what is stored at [`Self::dest`]. Its caller ([`Frame::delegated_caller`]) is the
+		/// what is stored at [`Self::Call::dest`]. Its caller ([`DelegatedCall::caller`]) is the
 		/// account which called the caller contract
 		delegated_call: Option<DelegatedCall<T, E>>,
 	},

substrate/frame/contracts/src/lib.rs

@@ -134,6 +134,9 @@ pub use crate::{
 	wasm::Determinism,
 };
 
+#[cfg(doc)]
+pub use crate::wasm::api_doc;
+
 type CodeHash<T> = <T as frame_system::Config>::Hash;
 type TrieId = BoundedVec<u8, ConstU32<128>>;
 type BalanceOf<T> =

substrate/frame/contracts/src/wasm/mod.rs

@@ -28,6 +28,10 @@ pub use crate::wasm::{
 	prepare::TryInstantiate,
 	runtime::{CallFlags, Environment, ReturnCode, Runtime, RuntimeCosts},
 };
+
+#[cfg(doc)]
+pub use crate::wasm::runtime::api_doc;
+
 use crate::{
 	exec::{ExecResult, Executable, ExportedFunction, Ext},
 	gas::GasMeter,
@@ -144,7 +148,7 @@ impl<T: Config> PrefabWasmModule<T> {
 	/// Create the module by checking and instrumenting `original_code`.
 	///
 	/// This does **not** store the module. For this one need to either call [`Self::store`]
-	/// or [`<Self as Executable>::execute`].
+	/// or [`<Self as Executable>::execute`][`Executable::execute`].
 	pub fn from_code(
 		original_code: Vec<u8>,
 		schedule: &Schedule<T>,
@@ -164,7 +168,8 @@ impl<T: Config> PrefabWasmModule<T> {
 
 	/// Store the code without instantiating it.
 	///
-	/// Otherwise the code is stored when [`<Self as Executable>::execute`] is called.
+	/// Otherwise the code is stored when [`<Self as Executable>::execute`][`Executable::execute`]
+	/// is called.
 	pub fn store(self) -> DispatchResult {
 		code_cache::store(self, false)
 	}

substrate/frame/contracts/src/wasm/runtime.rs

@@ -52,7 +52,7 @@ pub trait Environment<HostState> {
 /// Type of a storage key.
 #[allow(dead_code)]
 enum KeyType {
-	/// Deprecated fix sized key [0;32].
+	/// Deprecated fix sized key `[u8;32]`.
 	Fix,
 	/// Variable sized key used in transparent hashing,
 	/// cannot be larger than MaxStorageKeyLen.
@@ -996,14 +996,14 @@ impl<'a, E: Ext + 'a> Runtime<'a, E> {
 // Any input that leads to a out of bound error (reading or writing) or failing to decode
 // data passed to the supervisor will lead to a trap. This is not documented explicitly
 // for every function.
-#[define_env]
+#[define_env(doc)]
 pub mod env {
 	/// Account for used gas. Traps if gas used is greater than gas limit.
 	///
 	/// NOTE: This is a implementation defined call and is NOT a part of the public API.
 	/// This call is supposed to be called only by instrumentation injected code.
 	///
-	/// - amount: How much gas is used.
+	/// - `amount`: How much gas is used.
 	fn gas(ctx: _, _memory: _, amount: u64) -> Result<(), TrapReason> {
 		ctx.charge_gas(RuntimeCosts::MeteringBlock(amount))?;
 		Ok(())
@@ -1011,8 +1011,8 @@ pub mod env {
 
 	/// Set the value at the given key in the contract storage.
 	///
-	/// Equivalent to the newer version of `seal_set_storage` with the exception of the return
-	/// type. Still a valid thing to call when not interested in the return value.
+	/// Equivalent to the newer version [`super::seal1::Api::set_storage`] with the exception of the
+	/// return type. Still a valid thing to call when not interested in the return value.
 	#[prefixed_alias]
 	fn set_storage(
 		ctx: _,
@@ -1085,8 +1085,8 @@ pub mod env {
 
 	/// Clear the value at the given key in the contract storage.
 	///
-	/// Equivalent to the newer version of `seal_clear_storage` with the exception of the return
-	/// type. Still a valid thing to call when not interested in the return value.
+	/// Equivalent to the newer version [`super::seal1::Api::clear_storage`] with the exception of
+	/// the return type. Still a valid thing to call when not interested in the return value.
 	#[prefixed_alias]
 	fn clear_storage(ctx: _, memory: _, key_ptr: u32) -> Result<(), TrapReason> {
 		ctx.clear_storage(memory, KeyType::Fix, key_ptr).map(|_| ())
@@ -1152,7 +1152,7 @@ pub mod env {
 	///
 	/// # Errors
 	///
-	/// `ReturnCode::KeyNotFound`
+	/// - `ReturnCode::KeyNotFound`
 	#[version(1)]
 	#[prefixed_alias]
 	fn get_storage(
@@ -1215,7 +1215,7 @@ pub mod env {
 	///
 	/// # Errors
 	///
-	/// `ReturnCode::KeyNotFound`
+	/// - `ReturnCode::KeyNotFound`
 	#[prefixed_alias]
 	fn take_storage(
 		ctx: _,
@@ -1245,16 +1245,16 @@ pub mod env {
 	///
 	/// # Parameters
 	///
-	/// - account_ptr: a pointer to the address of the beneficiary account Should be decodable as an
-	///   `T::AccountId`. Traps otherwise.
-	/// - account_len: length of the address buffer.
-	/// - value_ptr: a pointer to the buffer with value, how much value to send. Should be decodable
-	///   as a `T::Balance`. Traps otherwise.
-	/// - value_len: length of the value buffer.
+	/// - `account_ptr`: a pointer to the address of the beneficiary account Should be decodable as
+	///   an `T::AccountId`. Traps otherwise.
+	/// - `account_len`: length of the address buffer.
+	/// - `value_ptr`: a pointer to the buffer with value, how much value to send. Should be
+	///   decodable as a `T::Balance`. Traps otherwise.
+	/// - `value_len`: length of the value buffer.
 	///
 	/// # Errors
 	///
-	/// `ReturnCode::TransferFailed`
+	/// - `ReturnCode::TransferFailed`
 	#[prefixed_alias]
 	fn transfer(
 		ctx: _,
@@ -1288,8 +1288,9 @@ pub mod env {
 	/// # Note
 	///
 	/// The values `_callee_len` and `_value_len` are ignored because the encoded sizes
-	/// of those types are fixed through `[`MaxEncodedLen`]. The fields exist for backwards
-	/// compatibility. Consider switching to the newest version of this function.
+	/// of those types are fixed through
+	/// [`codec::MaxEncodedLen`]. The fields exist
+	/// for backwards compatibility. Consider switching to the newest version of this function.
 	#[prefixed_alias]
 	fn call(
 		ctx: _,
@@ -1323,16 +1324,16 @@ pub mod env {
 	///
 	/// # Parameters
 	///
-	/// - flags: See [`CallFlags`] for a documenation of the supported flags.
-	/// - callee_ptr: a pointer to the address of the callee contract. Should be decodable as an
+	/// - `flags`: See `crate::wasm::runtime::CallFlags` for a documenation of the supported flags.
+	/// - `callee_ptr`: a pointer to the address of the callee contract. Should be decodable as an
 	///   `T::AccountId`. Traps otherwise.
-	/// - gas: how much gas to devote to the execution.
-	/// - value_ptr: a pointer to the buffer with value, how much value to send. Should be decodable
-	///   as a `T::Balance`. Traps otherwise.
-	/// - input_data_ptr: a pointer to a buffer to be used as input data to the callee.
-	/// - input_data_len: length of the input data buffer.
-	/// - output_ptr: a pointer where the output buffer is copied to.
-	/// - output_len_ptr: in-out pointer to where the length of the buffer is read from and the
+	/// - `gas`: how much gas to devote to the execution.
+	/// - `value_ptr`: a pointer to the buffer with value, how much value to send. Should be
+	///   decodable as a `T::Balance`. Traps otherwise.
+	/// - `input_data_ptr`: a pointer to a buffer to be used as input data to the callee.
+	/// - `input_data_len`: length of the input data buffer.
+	/// - `output_ptr`: a pointer where the output buffer is copied to.
+	/// - `output_len_ptr`: in-out pointer to where the length of the buffer is read from and the
 	///   actual length is written to.
 	///
 	/// # Errors
@@ -1340,10 +1341,10 @@ pub mod env {
 	/// An error means that the call wasn't successful output buffer is returned unless
 	/// stated otherwise.
 	///
-	/// `ReturnCode::CalleeReverted`: Output buffer is returned.
-	/// `ReturnCode::CalleeTrapped`
-	/// `ReturnCode::TransferFailed`
-	/// `ReturnCode::NotCallable`
+	/// - `ReturnCode::CalleeReverted`: Output buffer is returned.
+	/// - `ReturnCode::CalleeTrapped`
+	/// - `ReturnCode::TransferFailed`
+	/// - `ReturnCode::NotCallable`
 	#[version(1)]
 	#[prefixed_alias]
 	fn call(
@@ -1377,12 +1378,12 @@ pub mod env {
 	///
 	/// # Parameters
 	///
-	/// - flags: See [`CallFlags`] for a documentation of the supported flags.
-	/// - code_hash: a pointer to the hash of the code to be called.
-	/// - input_data_ptr: a pointer to a buffer to be used as input data to the callee.
-	/// - input_data_len: length of the input data buffer.
-	/// - output_ptr: a pointer where the output buffer is copied to.
-	/// - output_len_ptr: in-out pointer to where the length of the buffer is read from and the
+	/// - `flags`: see `crate::wasm::runtime::CallFlags` for a documentation of the supported flags.
+	/// - `code_hash`: a pointer to the hash of the code to be called.
+	/// - `input_data_ptr`: a pointer to a buffer to be used as input data to the callee.
+	/// - `input_data_len`: length of the input data buffer.
+	/// - `output_ptr`: a pointer where the output buffer is copied to.
+	/// - `output_len_ptr`: in-out pointer to where the length of the buffer is read from and the
 	///   actual length is written to.
 	///
 	/// # Errors
@@ -1390,9 +1391,9 @@ pub mod env {
 	/// An error means that the call wasn't successful and no output buffer is returned unless
 	/// stated otherwise.
 	///
-	/// `ReturnCode::CalleeReverted`: Output buffer is returned.
-	/// `ReturnCode::CalleeTrapped`
-	/// `ReturnCode::CodeNotFound`
+	/// - `ReturnCode::CalleeReverted`: Output buffer is returned.
+	/// - `ReturnCode::CalleeTrapped`
+	/// - `ReturnCode::CodeNotFound`
 	#[prefixed_alias]
 	fn delegate_call(
 		ctx: _,
@@ -1425,8 +1426,9 @@ pub mod env {
 	/// # Note
 	///
 	/// The values `_code_hash_len` and `_value_len` are ignored because the encoded sizes
-	/// of those types are fixed through `[`MaxEncodedLen`]. The fields exist for backwards
-	/// compatibility. Consider switching to the newest version of this function.
+	/// of those types are fixed through
+	/// [`codec::MaxEncodedLen`]. The fields exist
+	/// for backwards compatibility. Consider switching to the newest version of this function.
 	#[prefixed_alias]
 	fn instantiate(
 		ctx: _,
@@ -1474,20 +1476,20 @@ pub mod env {
 	///
 	/// # Parameters
 	///
-	/// - code_hash_ptr: a pointer to the buffer that contains the initializer code.
-	/// - gas: how much gas to devote to the execution of the initializer code.
-	/// - value_ptr: a pointer to the buffer with value, how much value to send. Should be decodable
-	///   as a `T::Balance`. Traps otherwise.
-	/// - input_data_ptr: a pointer to a buffer to be used as input data to the initializer code.
-	/// - input_data_len: length of the input data buffer.
-	/// - address_ptr: a pointer where the new account's address is copied to.
-	/// - address_len_ptr: in-out pointer to where the length of the buffer is read from and the
+	/// - `code_hash_ptr`: a pointer to the buffer that contains the initializer code.
+	/// - `gas`: how much gas to devote to the execution of the initializer code.
+	/// - `value_ptr`: a pointer to the buffer with value, how much value to send. Should be
+	///   decodable as a `T::Balance`. Traps otherwise.
+	/// - `input_data_ptr`: a pointer to a buffer to be used as input data to the initializer code.
+	/// - `input_data_len`: length of the input data buffer.
+	/// - `address_ptr`: a pointer where the new account's address is copied to.
+	/// - `address_len_ptr`: in-out pointer to where the length of the buffer is read from and the
 	///   actual length is written to.
-	/// - output_ptr: a pointer where the output buffer is copied to.
-	/// - output_len_ptr: in-out pointer to where the length of the buffer is read from and the
+	/// - `output_ptr`: a pointer where the output buffer is copied to.
+	/// - `output_len_ptr`: in-out pointer to where the length of the buffer is read from and the
 	///   actual length is written to.
-	/// - salt_ptr: Pointer to raw bytes used for address derivation. See `fn contract_address`.
-	/// - salt_len: length in bytes of the supplied salt.
+	/// - `salt_ptr`: Pointer to raw bytes used for address derivation. See `fn contract_address`.
+	/// - `salt_len`: length in bytes of the supplied salt.
 	///
 	/// # Errors
 	///
@@ -1497,10 +1499,10 @@ pub mod env {
 	/// An error means that the account wasn't created and no address or output buffer
 	/// is returned unless stated otherwise.
 	///
-	/// `ReturnCode::CalleeReverted`: Output buffer is returned.
-	/// `ReturnCode::CalleeTrapped`
-	/// `ReturnCode::TransferFailed`
-	/// `ReturnCode::CodeNotFound`
+	/// - `ReturnCode::CalleeReverted`: Output buffer is returned.
+	/// - `ReturnCode::CalleeTrapped`
+	/// - `ReturnCode::TransferFailed`
+	/// - `ReturnCode::CodeNotFound`
 	#[version(1)]
 	#[prefixed_alias]
 	fn instantiate(
@@ -1562,7 +1564,7 @@ pub mod env {
 	/// execution of the destroyed contract is halted. Or it failed during the termination
 	/// which is considered fatal and results in a trap + rollback.
 	///
-	/// - beneficiary_ptr: a pointer to the address of the beneficiary account where all where all
+	/// - `beneficiary_ptr`: a pointer to the address of the beneficiary account where all where all
 	///   remaining funds of the caller are transferred. Should be decodable as an `T::AccountId`.
 	///   Traps otherwise.
 	///
@@ -1586,7 +1588,7 @@ pub mod env {
 	///
 	/// # Note
 	///
-	/// This function traps if the input was previously forwarded by a `seal_call`.
+	/// This function traps if the input was previously forwarded by a [`call()`][`Self::call()`].
 	#[prefixed_alias]
 	fn input(ctx: _, memory: _, out_ptr: u32, out_len_ptr: u32) -> Result<(), TrapReason> {
 		ctx.charge_gas(RuntimeCosts::InputBase)?;
@@ -1606,7 +1608,7 @@ pub mod env {
 	/// This function never returns as it stops execution of the caller.
 	/// This is the only way to return a data buffer to the caller. Returning from
 	/// execution without calling this function is equivalent to calling:
-	/// ```
+	/// ```nocompile
 	/// seal_return(0, 0, 0);
 	/// ```
 	///
@@ -1659,10 +1661,10 @@ pub mod env {
 	///
 	/// # Parameters
 	///
-	/// - account_ptr: a pointer to the address of the beneficiary account Should be decodable as an
-	///   `T::AccountId`. Traps otherwise.
+	/// - `account_ptr`: a pointer to the address of the beneficiary account Should be decodable as
+	///   an `T::AccountId`. Traps otherwise.
 	///
-	/// Returned value is a u32-encoded boolean: (0 = false, 1 = true).
+	/// Returned value is a `u32`-encoded boolean: (0 = false, 1 = true).
 	#[prefixed_alias]
 	fn is_contract(ctx: _, memory: _, account_ptr: u32) -> Result<u32, TrapReason> {
 		ctx.charge_gas(RuntimeCosts::IsContract)?;
@@ -1684,7 +1686,7 @@ pub mod env {
 	///
 	/// # Errors
 	///
-	/// `ReturnCode::KeyNotFound`
+	/// - `ReturnCode::KeyNotFound`
 	#[prefixed_alias]
 	fn code_hash(
 		ctx: _,
@@ -1734,14 +1736,14 @@ pub mod env {
 
 	/// Checks whether the caller of the current contract is the origin of the whole call stack.
 	///
-	/// Prefer this over `seal_is_contract` when checking whether your contract is being called by a
-	/// contract or a plain account. The reason is that it performs better since it does not need to
-	/// do any storage lookups.
+	/// Prefer this over [`is_contract()`][`Self::is_contract`] when checking whether your contract
+	/// is being called by a contract or a plain account. The reason is that it performs better
+	/// since it does not need to do any storage lookups.
 	///
-	/// A return value of`true` indicates that this contract is being called by a plain account
+	/// A return value of `true` indicates that this contract is being called by a plain account
 	/// and `false` indicates that the caller is another contract.
 	///
-	/// Returned value is a u32-encoded boolean: (0 = false, 1 = true).
+	/// Returned value is a `u32`-encoded boolean: (`0 = false`, `1 = true`).
 	#[prefixed_alias]
 	fn caller_is_origin(ctx: _, _memory: _) -> Result<u32, TrapReason> {
 		ctx.charge_gas(RuntimeCosts::CallerIsOrigin)?;
@@ -1774,7 +1776,7 @@ pub mod env {
 	/// `out_ptr`. This call overwrites it with the size of the value. If the available
 	/// space at `out_ptr` is less than the size of the value a trap is triggered.
 	///
-	/// The data is encoded as T::Balance.
+	/// The data is encoded as `T::Balance`.
 	///
 	/// # Note
 	///
@@ -1822,14 +1824,14 @@ pub mod env {
 		)?)
 	}
 
-	/// Stores the **free* balance of the current account into the supplied buffer.
+	/// Stores the *free* balance of the current account into the supplied buffer.
 	///
 	/// The value is stored to linear memory at the address pointed to by `out_ptr`.
 	/// `out_len_ptr` must point to a u32 value that describes the available space at
 	/// `out_ptr`. This call overwrites it with the size of the value. If the available
 	/// space at `out_ptr` is less than the size of the value a trap is triggered.
 	///
-	/// The data is encoded as T::Balance.
+	/// The data is encoded as `T::Balance`.
 	#[prefixed_alias]
 	fn balance(ctx: _, memory: _, out_ptr: u32, out_len_ptr: u32) -> Result<(), TrapReason> {
 		ctx.charge_gas(RuntimeCosts::Balance)?;
@@ -1846,11 +1848,11 @@ pub mod env {
 	/// Stores the value transferred along with this call/instantiate into the supplied buffer.
 	///
 	/// The value is stored to linear memory at the address pointed to by `out_ptr`.
-	/// `out_len_ptr` must point to a u32 value that describes the available space at
+	/// `out_len_ptr` must point to a `u32` value that describes the available space at
 	/// `out_ptr`. This call overwrites it with the size of the value. If the available
 	/// space at `out_ptr` is less than the size of the value a trap is triggered.
 	///
-	/// The data is encoded as T::Balance.
+	/// The data is encoded as `T::Balance`.
 	#[prefixed_alias]
 	fn value_transferred(
 		ctx: _,
@@ -1876,11 +1878,12 @@ pub mod env {
 	/// `out_ptr`. This call overwrites it with the size of the value. If the available
 	/// space at `out_ptr` is less than the size of the value a trap is triggered.
 	///
-	/// The data is encoded as T::Hash.
+	/// The data is encoded as `T::Hash`.
 	///
 	/// # Deprecation
 	///
-	/// This function is deprecated. Users should migrate to the version in the "seal1" module.
+	/// This function is deprecated. Users should migrate to the [`super::seal1::Api::random()`]
+	/// version.
 	#[prefixed_alias]
 	fn random(
 		ctx: _,
@@ -1972,7 +1975,7 @@ pub mod env {
 
 	/// Stores the minimum balance (a.k.a. existential deposit) into the supplied buffer.
 	///
-	/// The data is encoded as T::Balance.
+	/// The data is encoded as `T::Balance`.
 	#[prefixed_alias]
 	fn minimum_balance(
 		ctx: _,
@@ -2000,7 +2003,7 @@ pub mod env {
 	///
 	/// # Deprecation
 	///
-	/// There is no longer a tombstone deposit. This function always returns 0.
+	/// There is no longer a tombstone deposit. This function always returns `0`.
 	#[prefixed_alias]
 	fn tombstone_deposit(
 		ctx: _,
@@ -2067,11 +2070,12 @@ pub mod env {
 	/// Deposit a contract event with the data buffer and optional list of topics. There is a limit
 	/// on the maximum number of topics specified by `event_topics`.
 	///
-	/// - topics_ptr - a pointer to the buffer of topics encoded as `Vec<T::Hash>`. The value of
-	///   this is ignored if `topics_len` is set to 0. The topics list can't contain duplicates.
-	/// - topics_len - the length of the topics buffer. Pass 0 if you want to pass an empty vector.
-	/// - data_ptr - a pointer to a raw data buffer which will saved along the event.
-	/// - data_len - the length of the data buffer.
+	/// - `topics_ptr`: a pointer to the buffer of topics encoded as `Vec<T::Hash>`. The value of
+	///   this is ignored if `topics_len` is set to `0`. The topics list can't contain duplicates.
+	/// - `topics_len`:  the length of the topics buffer. Pass 0 if you want to pass an empty
+	///   vector.
+	/// - `data_ptr`: a pointer to a raw data buffer which will saved along the event.
+	/// - `data_len`:  the length of the data buffer.
 	#[prefixed_alias]
 	fn deposit_event(
 		ctx: _,
@@ -2422,11 +2426,6 @@ pub mod env {
 	/// - Provide functionality **exclusively** to contracts.
 	/// - Provide custom weights.
 	/// - Avoid the need to keep the `Call` data structure stable.
-	///
-	/// # Unstable
-	///
-	/// This function is unstable and subject to change (or removal) in the future. Do not
-	/// deploy a contract using it to a production chain.
 	#[unstable]
 	#[prefixed_alias]
 	fn call_runtime(
@@ -2466,7 +2465,7 @@ pub mod env {
 	///
 	/// # Errors
 	///
-	/// `ReturnCode::EcdsaRecoverFailed`
+	/// - `ReturnCode::EcdsaRecoverFailed`
 	#[prefixed_alias]
 	fn ecdsa_recover(
 		ctx: _,
@@ -2513,8 +2512,8 @@ pub mod env {
 	///
 	/// 3. If a contract calls into itself after changing its code the new call would use
 	/// the new code. However, if the original caller panics after returning from the sub call it
-	/// would revert the changes made by `seal_set_code_hash` and the next caller would use
-	/// the old code.
+	/// would revert the changes made by [`set_code_hash()`][`Self::set_code_hash`] and the next
+	/// caller would use the old code.
 	///
 	/// # Parameters
 	///
@@ -2522,7 +2521,7 @@ pub mod env {
 	///
 	/// # Errors
 	///
-	/// `ReturnCode::CodeNotFound`
+	/// - `ReturnCode::CodeNotFound`
 	#[prefixed_alias]
 	fn set_code_hash(ctx: _, memory: _, code_hash_ptr: u32) -> Result<ReturnCode, TrapReason> {
 		ctx.charge_gas(RuntimeCosts::SetCodeHash)?;
@@ -2552,7 +2551,7 @@ pub mod env {
 	///
 	/// # Errors
 	///
-	/// `ReturnCode::EcdsaRecoverFailed`
+	/// - `ReturnCode::EcdsaRecoverFailed`
 	#[prefixed_alias]
 	fn ecdsa_to_eth_address(
 		ctx: _,
@@ -2578,7 +2577,7 @@ pub mod env {
 	///
 	/// # Return Value
 	///
-	/// Returns 0 when there is no reentrancy.
+	/// Returns `0` when there is no reentrancy.
 	#[unstable]
 	fn reentrance_count(ctx: _, memory: _) -> Result<u32, TrapReason> {
 		ctx.charge_gas(RuntimeCosts::ReentrantCount)?;
@@ -2594,7 +2593,7 @@ pub mod env {
 	///
 	/// # Return Value
 	///
-	/// Returns 0 when the contract does not exist on the call stack.
+	/// Returns `0` when the contract does not exist on the call stack.
 	#[unstable]
 	fn account_reentrance_count(ctx: _, memory: _, account_ptr: u32) -> Result<u32, TrapReason> {
 		ctx.charge_gas(RuntimeCosts::AccountEntranceCount)?;