Skip to content

Commit

Permalink
[improve docs] Example pallet crate and Basic Example pallet (#1546)
Browse files Browse the repository at this point in the history 
This fixes the broken links in the crate level documentation of the
Examples crate. It also updates the documentation for the Basic Example
pallet by removing the template for documenting a pallet (we now have
[this](https://github.com/paritytech/polkadot-sdk/blob/master/docs/DOCUMENTATION_GUIDELINE.md)
to refer to instead).

Note: I found it unnecessary to provide a link to the doc guidelines as
I don't think this would be where someone should discover them. I also
want to flag some ideas that came while making these minor improvements
in [this
issue](paritytech/polkadot-sdk-docs#27) (for a
subsequent PR) as part of ongoing docs work.
  • Loading branch information
Sacha Lansky committed Sep 18, 2023
1 parent a8e82a3 commit 1d5a9d2
Show file tree
Hide file tree
Showing 3 changed files with 42 additions and 256 deletions.
2 changes: 1 addition & 1 deletion substrate/frame/examples/Cargo.toml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ edition.workspace = true
license = "Apache-2.0"
homepage = "https://substrate.io"
repository.workspace = true
description = "The single package with various examples for frame pallets"
description = "The single package with examples of various types of FRAME pallets"

[package.metadata.docs.rs]
targets = ["x86_64-unknown-linux-gnu"]
Expand Down
267 changes: 25 additions & 242 deletions substrate/frame/examples/basic/src/lib.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,258 +15,40 @@
// See the License for the specific language governing permissions and
// limitations under the License.

//! <!-- markdown-link-check-disable -->
//! # Basic Example Pallet
//!
//! <!-- Original author of paragraph: @gavofyork -->
//! The Example: A simple example of a FRAME pallet demonstrating
//! concepts, APIs and structures common to most FRAME runtimes.
//!
//! Run `cargo doc --package pallet-example-basic --open` to view this pallet's documentation.
//! A pallet demonstrating concepts, APIs and structures common to most FRAME runtimes.
//!
//! **This pallet serves as an example and is not meant to be used in production.**
//!
//! ### Documentation Guidelines:
//!
//! <!-- Original author of paragraph: Various. Based on collation of review comments to PRs
//! addressing issues with --> <!-- label 'S3-FRAME' in https://github.com/paritytech/substrate-developer-hub/issues -->
//! <ul>
//! <li>Documentation comments (i.e. <code>/// comment</code>) - should
//! accompany pallet functions and be restricted to the pallet interface,
//! not the internals of the pallet implementation. Only state inputs,
//! outputs, and a brief description that mentions whether calling it
//! requires root, but without repeating the source code details.
//! Capitalize the first word of each documentation comment and end it with
//! a full stop. See
//! <a href="https://github.com/paritytech/substrate#72-contributing-to-documentation-for-substrate-packages"
//! target="_blank"> Generic example of annotating source code with documentation comments</a></li>
//!
//! <li>Self-documenting code - Try to refactor code to be self-documenting.</li>
//!
//! <li>Code comments - Supplement complex code with a brief explanation, not every line of
//! code.</li>
//!
//! <li>Identifiers - surround by backticks (i.e. <code>INHERENT_IDENTIFIER</code>,
//! <code>InherentType</code>, <code>u64</code>)</li>
//!
//! <li>Usage scenarios - should be simple doctests. The compiler should ensure they stay
//! valid.</li>
//!
//! <li>Extended tutorials - should be moved to external files and refer to.</li>
//!
//! <li>Mandatory - include all of the sections/subsections where <b>MUST</b> is specified.</li>
//!
//! <li>Optional - optionally include sections/subsections where <b>CAN</b> is specified.</li>
//! </ul>
//!
//! ### Documentation Template:<br>
//!
//! Copy and paste this template from frame/examples/basic/src/lib.rs into file
//! `frame/<INSERT_CUSTOM_PALLET_NAME>/src/lib.rs` of your own custom pallet and complete it.
//! <details><p><pre>
//! // Add heading with custom pallet name
//!
//! \# <INSERT_CUSTOM_PALLET_NAME> Pallet
//!
//! // Add simple description
//!
//! // Include the following links that shows what trait needs to be implemented to use the pallet
//! // and the supported dispatchables that are documented in the Call enum.
//!
//! - \[`Config`]
//! - \[`Call`]
//! - \[`Pallet`]
//!
//! \## Overview
//!
//! <!-- Original author of paragraph: Various. See https://github.com/paritytech/substrate-developer-hub/issues/44 -->
//! // Short description of pallet's purpose.
//! // Links to Traits that should be implemented.
//! // What this pallet is for.
//! // What functionality the pallet provides.
//! // When to use the pallet (use case examples).
//! // How it is used.
//! // Inputs it uses and the source of each input.
//! // Outputs it produces.
//!
//! <!-- Original author of paragraph: @Kianenigma in PR https://github.com/paritytech/substrate/pull/1951 -->
//! <!-- and comment https://github.com/paritytech/substrate-developer-hub/issues/44#issuecomment-471982710 -->
//!
//! \## Terminology
//!
//! // Add terminology used in the custom pallet. Include concepts, storage items, or actions that
//! you think // deserve to be noted to give context to the rest of the documentation or pallet
//! usage. The author needs to // use some judgment about what is included. We don't want a list of
//! every storage item nor types - the user // can go to the code for that. For example, "transfer
//! fee" is obvious and should not be included, but // "free balance" and "reserved balance" should
//! be noted to give context to the pallet. // Please do not link to outside resources. The
//! reference docs should be the ultimate source of truth.
//!
//! <!-- Original author of heading: @Kianenigma in PR https://github.com/paritytech/substrate/pull/1951 -->
//!
//! \## Goals
//!
//! // Add goals that the custom pallet is designed to achieve.
//!
//! <!-- Original author of heading: @Kianenigma in PR https://github.com/paritytech/substrate/pull/1951 -->
//!
//! \### Scenarios
//!
//! <!-- Original author of paragraph: @Kianenigma. Based on PR https://github.com/paritytech/substrate/pull/1951 -->
//!
//! \#### <INSERT_SCENARIO_NAME>
//!
//! // Describe requirements prior to interacting with the custom pallet.
//! // Describe the process of interacting with the custom pallet for this scenario and public API
//! functions used.
//!
//! \## Interface
//!
//! \### Supported Origins
//!
//! // What origins are used and supported in this pallet (root, signed, none)
//! // i.e. root when <code>\`ensure_root\`</code> used
//! // i.e. none when <code>\`ensure_none\`</code> used
//! // i.e. signed when <code>\`ensure_signed\`</code> used
//!
//! <code>\`inherent\`</code> <INSERT_DESCRIPTION>
//!
//! <!-- Original author of paragraph: @Kianenigma in comment -->
//! <!-- https://github.com/paritytech/substrate-developer-hub/issues/44#issuecomment-471982710 -->
//!
//! \### Types
//!
//! // Type aliases. Include any associated types and where the user would typically define them.
//!
//! <code>\`ExampleType\`</code> <INSERT_DESCRIPTION>
//!
//! <!-- Original author of paragraph: ??? -->
//!
//! // Reference documentation of aspects such as `storageItems` and `dispatchable` functions should
//! // only be included in the <https://docs.rs> Rustdocs for Substrate and not repeated in the
//! // README file.
//!
//! \### Dispatchable Functions
//!
//! <!-- Original author of paragraph: @AmarRSingh & @joepetrowski -->
//!
//! // A brief description of dispatchable functions and a link to the rustdoc with their actual
//! documentation.
//!
//! // <b>MUST</b> have link to Call enum
//! // <b>MUST</b> have origin information included in function doc
//! // <b>CAN</b> have more info up to the user
//!
//! \### Public Functions
//!
//! <!-- Original author of paragraph: @joepetrowski -->
//!
//! // A link to the rustdoc and any notes about usage in the pallet, not for specific functions.
//! // For example, in the Balances Pallet: "Note that when using the publicly exposed functions,
//! // you (the runtime developer) are responsible for implementing any necessary checks
//! // (e.g. that the sender is the signer) before calling a function that will affect storage."
//!
//! <!-- Original author of paragraph: @AmarRSingh -->
//!
//! // It is up to the writer of the respective pallet (with respect to how much information to
//! provide).
//!
//! \#### Public Inspection functions - Immutable (getters)
//!
//! // Insert a subheading for each getter function signature
//!
//! \##### <code>\`example_getter_name()\`</code>
//!
//! // What it returns
//! // Why, when, and how often to call it
//! // When it could panic or error
//! // When safety issues to consider
//!
//! \#### Public Mutable functions (changing state)
//!
//! // Insert a subheading for each setter function signature
//!
//! \##### <code>\`example_setter_name(origin, parameter_name: T::ExampleType)\`</code>
//!
//! // What state it changes
//! // Why, when, and how often to call it
//! // When it could panic or error
//! // When safety issues to consider
//! // What parameter values are valid and why
//!
//! \### Storage Items
//!
//! // Explain any storage items included in this pallet
//!
//! \### Digest Items
//!
//! // Explain any digest items included in this pallet
//!
//! \### Inherent Data
//!
//! // Explain what inherent data (if any) is defined in the pallet and any other related types
//!
//! \### Events:
//!
//! // Insert events for this pallet if any
//!
//! \### Errors:
//!
//! // Explain what generates errors
//!
//! \## Usage
//!
//! // Insert 2-3 examples of usage and code snippets that show how to
//! // use <INSERT_CUSTOM_PALLET_NAME> Pallet in a custom pallet.
//!
//! \### Prerequisites
//!
//! // Show how to include necessary imports for <INSERT_CUSTOM_PALLET_NAME> and derive
//! // your pallet configuration trait with the `INSERT_CUSTOM_PALLET_NAME` trait.
//!
//! \```rust
//! use <INSERT_CUSTOM_PALLET_NAME>;
//!
//! pub trait Config: <INSERT_CUSTOM_PALLET_NAME>::Config { }
//! \```
//!
//! \### Simple Code Snippet
//!
//! // Show a simple example (e.g. how to query a public getter function of
//! <INSERT_CUSTOM_PALLET_NAME>)
//!
//! \### Example from FRAME
//!
//! // Show a usage example in an actual runtime
//!
//! // See:
//! // - Substrate TCR <https://github.com/parity-samples/substrate-tcr>
//! // - Substrate Kitties <https://shawntabrizi.github.io/substrate-collectables-workshop/#/>
//!
//! \## Genesis Config
//!
//! <!-- Original author of paragraph: @joepetrowski -->
//!
//! \## Dependencies
//! > Made with *Substrate*, for *Polkadot*.
//!
//! // Dependencies on other FRAME pallets and the genesis config should be mentioned,
//! // but not the Rust Standard Library.
//! // Genesis configuration modifications that may be made to incorporate this pallet
//! // Interaction with other pallets
//! [![github]](https://github.com/paritytech/polkadot-sdk/tree/master/substrate/frame/examples/basic)
//! [![polkadot]](https://polkadot.network)
//!
//! <!-- Original author of heading: @AmarRSingh -->
//! [polkadot]: https://img.shields.io/badge/polkadot-E6007A?style=for-the-badge&logo=polkadot&logoColor=white
//! [github]: https://img.shields.io/badge/github-8da0cb?style=for-the-badge&labelColor=555555&logo=github
//!
//! \## Related Pallets
//! ## Pallet API
//!
//! // Interaction with other pallets in the form of a bullet point list
//! See the [`pallet`] module for more information about the interfaces this pallet exposes,
//! including its configuration trait, dispatchables, storage items, events and errors.
//!
//! \## References
//! ## Overview
//!
//! <!-- Original author of paragraph: @joepetrowski -->
//! This pallet provides basic examples of using:
//!
//! // Links to reference material, if applicable. For example, Phragmen, W3F research, etc.
//! // that the implementation is based on.
//! </pre></p></details>
//! - A custom weight calculator able to classify a call's dispatch class (see:
//! [`frame_support::dispatch::DispatchClass`])
//! - Pallet hooks to implement some custom logic that's executed before and after a block is
//! imported (see: [`frame_support::traits::Hooks`])
//! - Inherited weight annotation for pallet calls, used to create less repetition for calls that
//! use the [`Config::WeightInfo`] trait to calculate call weights. This can also be overridden,
//! as demonstrated by [`Call::set_dummy`].
//! - A private function that performs a storage update.
//! - A simple signed extension implementation (see: [`sp_runtime::traits::SignedExtension`]) which
//! increases the priority of the [`Call::set_dummy`] if it's present and drops any transaction
//! with an encoded length higher than 200 bytes.

// Ensure we're `no_std` when compiling for Wasm.
#![cfg_attr(not(feature = "std"), no_std)]
Expand Down Expand Up @@ -381,7 +163,8 @@ pub mod pallet {
#[pallet::pallet]
pub struct Pallet<T>(_);

// Pallet implements [`Hooks`] trait to define some logic to execute in some context.
// This pallet implements the [`frame_support::traits::Hooks`] trait to define some logic to
// execute in some context.
#[pallet::hooks]
impl<T: Config> Hooks<BlockNumberFor<T>> for Pallet<T> {
// `on_initialize` is executed at the beginning of the block before any extrinsic are
Expand Down Expand Up @@ -686,7 +469,7 @@ impl<T: Config> Pallet<T> {
// sender of the transaction (if signed) are also provided.
//
// The full list of hooks that can be added to a signed extension can be found
// [here](https://crates.parity.io/sp_runtime/traits/trait.SignedExtension.html).
// [here](https://paritytech.github.io/polkadot-sdk/master/sp_runtime/traits/trait.SignedExtension.html).
//
// The signed extensions are aggregated in the runtime file of a substrate chain. All extensions
// should be aggregated in a tuple and passed to the `CheckedExtrinsic` and `UncheckedExtrinsic`
Expand Down
29 changes: 16 additions & 13 deletions substrate/frame/examples/src/lib.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,24 +17,27 @@

//! # FRAME Pallet Examples
//!
//! This crate contains examples of FRAME pallets. It is not intended to be used in production.
//! This crate contains a collection of simple examples of FRAME pallets, demonstrating useful
//! features in action. It is not intended to be used in production.
//!
//! ## Pallets
//!
//! - [**`pallet_example_basic`**](./basic): A simple example of a FRAME pallet demonstrating
//! concepts, APIs and structures common to most FRAME runtimes.
//! - [`pallet_example_basic`]: This pallet demonstrates concepts, APIs and structures common to
//! most FRAME runtimes.
//!
//! - [**`pallet_example_offchain_worker`**](./offchain-worker): A simple example of a FRAME pallet
//! demonstrating concepts, APIs and structures common to most offchain workers.
//! - [`pallet_example_offchain_worker`]: This pallet demonstrates concepts, APIs and structures
//! common to most offchain workers.
//!
//! - [**`pallet-default-config-example`**](./default-config): A simple example of a FRAME pallet
//! demonstrating the simpler way to implement `Config` trait of pallets.
//! - [`pallet_default_config_example`]: This pallet demonstrates different ways to implement the
//! `Config` trait of pallets.
//!
//! - [**`pallet-dev-mode`**](./dev-mode): A simple example of a FRAME pallet demonstrating the ease
//! of requirements for a pallet in dev mode.
//! - [`pallet_dev_mode`]: This pallet demonstrates the ease of requirements for a pallet in "dev
//! mode".
//!
//! - [**`pallet-example-kitchensink`**](./kitchensink): A simple example of a FRAME pallet
//! demonstrating a catalog of the the FRAME macros and their various syntax options.
//! - [`pallet_example_kitchensink`]: This pallet demonstrates a catalog of all FRAME macros in use
//! and their various syntax options.
//!
//! - [**`pallet-example-split`**](./split): A simple example of a FRAME pallet demonstrating the
//! ability to split sections across multiple files.
//! - [`pallet_example_split`]: A simple example of a FRAME pallet demonstrating the ability to
//! split sections across multiple files.
//!
//! **Tip**: Use `cargo doc --package <pallet-name> --open` to view each pallet's documentation.

0 comments on commit 1d5a9d2

Please sign in to comment.