Skip to content
Snippets Groups Projects
Unverified Commit 1d5a9d25 authored by Sacha Lansky's avatar Sacha Lansky Committed by GitHub
Browse files

[improve docs] Example pallet crate and Basic Example pallet (#1546) 

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](https://github.com/paritytech/polkadot-sdk-docs/issues/27) (for a
subsequent PR) as part of ongoing docs work.
parent a8e82a36
Branches
No related merge requests found
Pipeline #391644 canceled with stages
in 4 minutes and 4 seconds
Hide whitespace changes
Inline Side-by-side
substrate/frame/examples/Cargo.toml
+ 1
− 1
View file @ 1d5a9d25
......@@ -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"]
......
substrate/frame/examples/basic/src/lib.rs
+ 25
− 242
View file @ 1d5a9d25
......@@ -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`
......
substrate/frame/examples/src/lib.rs
+ 16
− 13
View file @ 1d5a9d25
......@@ -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% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment