Better documentation for the Deref abstraction

Signed-off-by: Alexandru Vasile <[email protected]>

frame/support/procedural/src/construct_runtime/expand/metadata.rs

@@ -77,6 +77,22 @@ pub fn expand_runtime_metadata(
 	quote! {
 		impl #runtime {
 			fn metadata_ir() -> #scrate::metadata_ir::MetadataIR {
+				// Each runtime must expose the `runtime_metadata()` to fetch the runtime API metadata.
+				// The function is implemented by calling `impl_runtime_apis!`.
+				//
+				// However, the `construct_runtime!` may be called without calling `impl_runtime_apis!`.
+				// Rely on the `Deref` trait to differentiate between a runtime that implements
+				// APIs (by macro impl_runtime_apis!) and a runtime that is simply created (by macro construct_runtime!).
+				//
+				// Both `InternalConstructRuntime` and `InternalImplRuntimeApis` expose a `runtime_metadata()` function.
+				// `InternalConstructRuntime` is implemented by the `construct_runtime!` for Runtime references (`& Runtime`),
+				// while `InternalImplRuntimeApis` is implemented by the `impl_runtime_apis!` for Runtime (`Runtime`).
+				//
+				// Therefore, the `Deref` trait will resolve the `runtime_metadata` from `impl_runtime_apis!`
+				// when both macros are called; and will resolve an empty `runtime_metadata` when only the `construct_runtime!`
+				// is called.
+				//
+				// `Deref` needs a reference for resolving the function call.
 				let rt = #runtime;
 
 				#scrate::metadata_ir::MetadataIR {

frame/support/procedural/src/construct_runtime/mod.rs

@@ -289,12 +289,29 @@ fn construct_runtime_final_expansion(
 			type RuntimeBlock = #block;
 		}
 
+		// Each runtime must expose the `runtime_metadata()` to fetch the runtime API metadata.
+		// The function is implemented by calling `impl_runtime_apis!`.
+		//
+		// However, the `construct_runtime!` may be called without calling `impl_runtime_apis!`.
+		// Rely on the `Deref` trait to differentiate between a runtime that implements
+		// APIs (by macro impl_runtime_apis!) and a runtime that is simply created (by macro construct_runtime!).
+		//
+		// Both `InternalConstructRuntime` and `InternalImplRuntimeApis` expose a `runtime_metadata()` function.
+		// `InternalConstructRuntime` is implemented by the `construct_runtime!` for Runtime references (`& Runtime`),
+		// while `InternalImplRuntimeApis` is implemented by the `impl_runtime_apis!` for Runtime (`Runtime`).
+		//
+		// Therefore, the `Deref` trait will resolve the `runtime_metadata` from `impl_runtime_apis!`
+		// when both macros are called; and will resolve an empty `runtime_metadata` when only the `construct_runtime!`
+		// is called.
+
+		#[doc(hidden)]
 		trait InternalConstructRuntime {
 			#[inline(always)]
 			fn runtime_metadata(&self) -> #scrate::sp_std::vec::Vec<#scrate::metadata_ir::RuntimeApiMetadataIR> {
 				Default::default()
 			}
 		}
+		#[doc(hidden)]
 		impl InternalConstructRuntime for &#name {}
 
 		#outer_event

primitives/api/proc-macro/src/runtime_metadata.rs

@@ -240,6 +240,23 @@ pub fn generate_impl_runtime_metadata(
 		));
 	}
 
+	// Each runtime must expose the `runtime_metadata()` to fetch the runtime API metadata.
+	// The function is implemented by calling `impl_runtime_apis!`.
+	//
+	// However, the `construct_runtime!` may be called without calling `impl_runtime_apis!`.
+	// Rely on the `Deref` trait to differentiate between a runtime that implements
+	// APIs (by macro impl_runtime_apis!) and a runtime that is simply created (by macro
+	// construct_runtime!).
+	//
+	// Both `InternalConstructRuntime` and `InternalImplRuntimeApis` expose a `runtime_metadata()`
+	// function. `InternalConstructRuntime` is implemented by the `construct_runtime!` for Runtime
+	// references (`& Runtime`), while `InternalImplRuntimeApis` is implemented by the
+	// `impl_runtime_apis!` for Runtime (`Runtime`).
+	//
+	// Therefore, the `Deref` trait will resolve the `runtime_metadata` from `impl_runtime_apis!`
+	// when both macros are called; and will resolve an empty `runtime_metadata` when only the
+	// `construct_runtime!` is called.
+
 	Ok(quote!(
 		#[doc(hidden)]
 		trait InternalImplRuntimeApis {