sp-version: Add some more docs. (#10486)

* sp-version: Add some more docs.

* Apply suggestions from code review

Co-authored-by: Shawn Tabrizi <shawntabrizi@gmail.com>

* Update lib.rs

Co-authored-by: Shawn Tabrizi <shawntabrizi@gmail.com>

primitives/version/Cargo.toml

@@ -13,7 +13,6 @@ readme = "README.md"
 [package.metadata.docs.rs]
 targets = ["x86_64-unknown-linux-gnu"]
 
-
 [dependencies]
 impl-serde = { version = "0.3.1", optional = true }
 serde = { version = "1.0.126", optional = true, features = ["derive"] }

primitives/version/src/lib.rs

@@ -15,7 +15,21 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-//! Version module for the Substrate runtime; Provides a function that returns the runtime version.
+//! Substrate runtime version
+//!
+//! Each runtime that should be executed by a Substrate based node needs to have a runtime version.
+//! The runtime version is defined by [`RuntimeVersion`]. The runtime version is used to
+//! distinguish different runtimes. The most important field is the
+//! [`spec_version`](RuntimeVersion::spec_version). The `spec_version` should be increased in a
+//! runtime when a new runtime build includes breaking changes that would make other runtimes unable
+//! to import blocks built by this runtime or vice-versa, where the new runtime could not import
+//! blocks built by the old runtime. The runtime version also carries other version information
+//! about the runtime, see [`RuntimeVersion`] for more information on this.
+//!
+//! Substrate will fetch the runtime version from a `wasm` blob by first checking the
+//! `runtime_version` link section or calling the `Core::version` runtime api. The link section can
+//! be generated in the runtime using the [`runtime_version`] attribute. The `Core` runtime api also
+//! needs to be implemented for the runtime using `impl_runtime_apis!`.
 
 #![cfg_attr(not(feature = "std"), no_std)]
 
@@ -104,7 +118,23 @@ pub use sp_version_proc_macro::runtime_version;
 /// The id is generated by hashing the name of the runtime api with BLAKE2 using a hash size
 /// of 8 bytes.
 ///
-/// The name of the runtime api is the name of the trait when using `decl_runtime_apis!` macro.
+/// The name of the runtime api is the name of the trait when using `decl_runtime_apis!` macro. So,
+/// in the following runtime api declaration:
+///
+/// ```nocompile
+/// decl_runtime_apis! {
+///     trait TestApi {
+///         fn do_test();
+///     }
+/// }
+/// ```
+///
+/// The name of the trait would be `TestApi` and would be taken as input to the BLAKE2 hash
+/// function.
+///
+/// As Rust supports renaming of traits, the name of a runtime api given to `impl_runtime_apis!`
+/// doesn't need to be the same as in `decl_runtime_apis!`, but only the name in
+/// `decl_runtime_apis!` is the important one!
 pub type ApiId = [u8; 8];
 
 /// A vector of pairs of `ApiId` and a `u32` for version.
@@ -216,12 +246,16 @@ impl RuntimeVersion {
 	}
 }
 
-#[cfg(feature = "std")]
+/// The version of the native runtime.
+///
+/// In contrast to the bare [`RuntimeVersion`] this also carries a list of `spec_version`s of
+/// runtimes this native runtime can be used to author blocks for.
 #[derive(Debug)]
+#[cfg(feature = "std")]
 pub struct NativeVersion {
 	/// Basic runtime version info.
 	pub runtime_version: RuntimeVersion,
-	/// Authoring runtimes that this native runtime supports.
+	/// Authoring runtimes (`spec_version`s) that this native runtime supports.
 	pub can_author_with: HashSet<u32>,
 }