pezkuwi-subxt/substrate/frame/example

Example Pallet

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 --open to view this pallet's documentation.

Documentation Guidelines:

• Documentation comments (i.e. /// comment) - 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 Generic example of annotating source code with documentation comments
• Self-documenting code - Try to refactor code to be self-documenting.
• Code comments - Supplement complex code with a brief explanation, not every line of code.
• Identifiers - surround by backticks (i.e. INHERENT_IDENTIFIER, InherentType, u64)
• Usage scenarios - should be simple doctests. The compiler should ensure they stay valid.
• Extended tutorials - should be moved to external files and refer to.
• Mandatory - include all of the sections/subsections where MUST is specified.
• Optional - optionally include sections/subsections where CAN is specified.

Documentation Template:

Copy and paste this template from frame/example/src/lib.rs into file frame/<INSERT_CUSTOM_PALLET_NAME>/src/lib.rs of your own custom pallet and complete it.

// 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.

[<INSERT_CUSTOM_PALLET_NAME>::Config](https://docs.rs/pallet-example/latest/pallet_example/trait.Config.html)
[Call](https://docs.rs/pallet-example/latest/pallet_example/enum.Call.html)
[Module](https://docs.rs/pallet-example/latest/pallet_example/struct.Module.html)

## Overview

// 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.


## 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.

## Goals
// Add goals that the custom pallet is designed to achieve.

### Scenarios

#### <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 `ensure_root` used
// i.e. none when `ensure_none` used
// i.e. signed when `ensure_signed` used
`inherent` <INSERT_DESCRIPTION>


### Types
// Type aliases. Include any associated types and where the user would typically define them.
`ExampleType` <INSERT_DESCRIPTION>

// 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

// A brief description of dispatchable functions and a link to the rustdoc with their actual documentation.
// MUST have link to Call enum
// MUST have origin information included in function doc
// CAN have more info up to the user
### Public Functions

// 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."

// 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
##### `example_getter_name()`
// 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
##### `example_setter_name(origin, parameter_name: T::ExampleType)`
// 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

## 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

## Related Pallets
// Interaction with other pallets in the form of a bullet point list
## References

// Links to reference material, if applicable. For example, Phragmen, W3F research, etc.
// that the implementation is based on.

License: Unlicense