pezkuwichain/pezkuwi-subxt
1
0
Fork 0
mirror of https://github.com/pezkuwichain/pezkuwi-subxt.git synced 2026-04-26 02:57:57 +00:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
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.
This commit is contained in:
Sacha Lansky
2023-09-18 11:05:12 +02:00
committed by GitHub
parent a8e82a365e
commit 1d5a9d25e2
3 changed files with 42 additions and 256 deletions
Download Patch File Download Diff File Expand all files Collapse all files
substrate/frame/examples/basic/src/lib.rs
+25 -242
View File
@@ -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:
//! > Made with *Substrate*, for *Polkadot*.
//!
//! <!-- 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>
//! [![github]](https://github.com/paritytech/polkadot-sdk/tree/master/substrate/frame/examples/basic)
//! [![polkadot]](https://polkadot.network)
//!
//! <li>Self-documenting code - Try to refactor code to be self-documenting.</li>
//! [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
//!
//! <li>Code comments - Supplement complex code with a brief explanation, not every line of
//! code.</li>
//! ## Pallet API
//!
//! <li>Identifiers - surround by backticks (i.e. <code>INHERENT_IDENTIFIER</code>,
//! <code>InherentType</code>, <code>u64</code>)</li>
//! See the [`pallet`] module for more information about the interfaces this pallet exposes,
//! including its configuration trait, dispatchables, storage items, events and errors.
//!
//! <li>Usage scenarios - should be simple doctests. The compiler should ensure they stay
//! valid.</li>
//! ## Overview
//!
//! <li>Extended tutorials - should be moved to external files and refer to.</li>
//! This pallet provides basic examples of using:
//!
//! <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
//!
//! // 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
//!
//! <!-- Original author of heading: @AmarRSingh -->
//!
//! \## Related Pallets
//!
//! // Interaction with other pallets in the form of a bullet point list
//!
//! \## References
//!
//! <!-- Original author of paragraph: @joepetrowski -->
//!
//! // 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`