Docs: Adhering to Substrate Code Documentation Guidelines (Pallets).

[sameh-farouk]

The following link provides a general overview of the code documentation guidelines that are recommended for Substrate projects: https://github.com/paritytech/substrate/blob/master/docs/DOCUMENTATION_GUIDELINES.md

One of the sections that is especially important for pallet development is the one that covers how to document various parts of the pallet code, such as dispatchables, storage items, errors and events.

There are two important points to keep in mind when documenting code during pallet development:

• Rust Docs vs. Code Comments Rust docs are comments that start with /// and are visible in the generated documentation. Code comments are comments that start with // and are only visible in the source code. It is essential to use them appropriately and not to mix them up.

• Pallet Documentation and Metadata Rust docs for pallets have an additional advantage: they can be used to generate metadata for the associated dispatchables, which can then be consumed by wallets and explorers, such as the hosted Polkadot UI. This makes the pallet API more user-friendly and accessible.

To illustrate the difference, see the screenshots below of the Polkadot UI for one of our custom pallet dispatchables (without dispatchables docs) and a standard Substrate pallet with proper dispatchables docs.

balances pallet

tfgrid pallet

See also pallet-fast-unstake as another example of adhering these guidelines.