diff --git a/substrate/frame/examples/Cargo.toml b/substrate/frame/examples/Cargo.toml index b072416b6121da41123b1e6276351306d128c6ab..9c47d7442111fdfa0313af5b9d1ae2048ae90b12 100644 --- a/substrate/frame/examples/Cargo.toml +++ b/substrate/frame/examples/Cargo.toml @@ -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"] diff --git a/substrate/frame/examples/basic/src/lib.rs b/substrate/frame/examples/basic/src/lib.rs index 426e9b7ec648c25dda54b27b498cbdd1d92b51d6..31d20e07f5f74ea18815b37ef4e93ec4ed6136bc 100644 --- a/substrate/frame/examples/basic/src/lib.rs +++ b/substrate/frame/examples/basic/src/lib.rs @@ -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)] @@ -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 @@ -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` diff --git a/substrate/frame/examples/src/lib.rs b/substrate/frame/examples/src/lib.rs index d1cd32bb50f263429567b4872ca5049f08586ac3..a7084fc6ef9bcb465952ec1203323b3d6db99322 100644 --- a/substrate/frame/examples/src/lib.rs +++ b/substrate/frame/examples/src/lib.rs @@ -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.