Repository: paritytech/substrate
File: src/lib.rs (Rust)

Code before:
//! ### Binaries
//!
//! Multiple binaries are shipped with substrate, the most important of which are located in the
//! `./bin` folder.
//!
//! * [`node`] is an extensive substrate node that contains the superset of all runtime and client
//!   side features. The corresponding runtime, called [`kitchensink_runtime`] contains all of the
//!   modules that are provided with `FRAME`. This node and runtime is only used for testing.
//! * [`node-template`]: a template node that contains a minimal set of features and can act as a
//!   starting point of a project.
//! * [`subkey`]: Substrate's key management utility.
//! * [`chain-spec-builder`]: Substrate's utility to build *chain specifications*. Such
//!   specifications can then be used with `--chain` argument of a typical substrate node's CLI.
//!
//! ### Anatomy of a Binary Crate
//!
//! From the above, [`node`] and [`node-template`] are essentially blueprints of a substrate-based
//! project, as the name of the latter is implying. Each substrate-based project typically contains
//! the following:
//!
//! * Under `./runtime`, a `./runtime/src/lib.rs` which is the top level runtime amalgamator file.
//!   This file typically contains the [`frame_support::construct_runtime`] macro, which is the
//!   final definition of a runtime.
//!
//! * Under `./node`, a `main.rs`, which is the point, and a `./service.rs`, which contains all the
//!   client side components. Skimming this file yield an overview of the networking, database,
//!   consensus and similar client side components.
//!
//! > The above two are conventions, not rules.
//!
//! ## Parachain?
//!
//! As noted above, Substrate is the main engine behind the Polkadot ecosystem. One of the ways
//! through which Polkadot can be utilized is by building "parachains", blockchains that are
//! connected to Polkadot's shared security.
//!
//! To build a parachain, one could use [`Cumulus`](https://github.com/paritytech/cumulus/), the
//! library on top of Substrate, empowering any substrate-based chain to be a Polkadot parachain.
//!
//! ## Where To Go Next?
//!
//! Additional noteworthy crates within substrate:
//!
//! - RPC APIs of a Substrate node: [`sc-rpc-api`]/[`sc-rpc`]
//! - CLI Options of a Substrate node: [`sc-cli`]
//! - All of the consensus related crates provided by Substrate:
//!     - [`sc-consensus-aura`]
//!     - [`sc-consensus-babe`]
//!     - [`sc-consensus-grandpa`]
//!     - [`sc-consensus-beefy`]
//!     - [`sc-consensus-manual-seal`]

Review comment (suggestion):
```suggestion
//!   client side components. Skimming this file yields an overview of the networking, database,
```

Code after:
//! ### Binaries
//!
//! Multiple binaries are shipped with substrate, the most important of which are located in the
//! `./bin` folder.
//!
//! * [`node`] is an extensive substrate node that contains the superset of all runtime and client
//!   side features. The corresponding runtime, called [`kitchensink_runtime`] contains all of the
//!   modules that are provided with `FRAME`. This node and runtime is only used for testing and
//!   demonstration.
//!     * [`chain-spec-builder`]: Utility to build more detailed chain-specs for the aforementioned
//!       node. Other projects typically contain a `build-spec` subcommand that does the same.
//! * [`node-template`]: a template node that contains a minimal set of features and can act as a
//!   starting point of a project.
//! * [`subkey`]: Substrate's key management utility.
//!
//! ### Anatomy of a Binary Crate
//!
//! From the above, [`node`] and [`node-template`] are essentially blueprints of a substrate-based
//! project, as the name of the latter is implying. Each substrate-based project typically contains
//! the following:
//!
//! * Under `./runtime`, a `./runtime/src/lib.rs` which is the top level runtime amalgamator file.
//!   This file typically contains the [`frame_support::construct_runtime`] macro, which is the
//!   final definition of a runtime.
//!
//! * Under `./node`, a `main.rs`, which is the point, and a `./service.rs`, which contains all the
//!   client side components. Skimming this file yields an overview of the networking, database,
//!   consensus and similar client side components.
//!
//! > The above two are conventions, not rules.
//!
//! ## Parachain?
//!
//! As noted above, Substrate is the main engine behind the Polkadot ecosystem. One of the ways
//! through which Polkadot can be utilized is by building "parachains", blockchains that are
//! connected to Polkadot's shared security.
//!
//! To build a parachain, one could use [`Cumulus`](https://github.com/paritytech/cumulus/), the
//! library on top of Substrate, empowering any substrate-based chain to be a Polkadot parachain.
//!
//! ## Where To Go Next?
//!
//! Additional noteworthy crates within substrate:
//!
//! - RPC APIs of a Substrate node: [`sc-rpc-api`]/[`sc-rpc`]
//! - CLI Options of a Substrate node: [`sc-cli`]
//! - All of the consensus related crates provided by Substrate:
//!     - [`sc-consensus-aura`]
//!     - [`sc-consensus-babe`]
//!     - [`sc-consensus-grandpa`]
//!     - [`sc-consensus-beefy`]