mirror of
https://github.com/pezkuwichain/pezkuwi-subxt.git
synced 2026-06-12 13:31:10 +00:00
Documentation for example module (#1947)
* WIP: SRML Example Module README * add newlines * review-fix: Change const to let. Explain generic usage more * refactor: Remove example steps 2 and 3. User can refer to other examples to figure it out * fix: Update to incorporate approved approach of staking module docs in PR #1951 * fix: Move into expandable Details arrow and fix syntax so appears correctly in rust docs * fix: Fix linting * docs: Add Public Dispatchable functions * fix: Rearrange to use Simple Code Snippet and Examples from SRML * fix: Remove duplicate Dispatchable Functions section * fix: Remove Implementation Details as requested by Gav
This commit is contained in:
Luke Schoen
@@ -14,8 +14,230 @@
|
||||
// You should have received a copy of the GNU General Public License
|
||||
// along with Substrate. If not, see <http://www.gnu.org/licenses/>.
|
||||
|
||||
//! # Example Module
|
||||
//!
|
||||
//! <!-- Original author of paragraph: @gavofyork -->
|
||||
//! The Example: A simple example of a runtime module demonstrating
|
||||
//! concepts, APIs and structures common to most runtime modules.
|
||||
//!
|
||||
//! Run `cargo doc --package srml-example --open` to view this module's documentation.
|
||||
//!
|
||||
//! ### Documentation Guidelines:
|
||||
//!
|
||||
//! <!-- Original author of paragraph: Various. Based on collation of review comments to PRs addressing issues with label 'S3-SRML' in https://github.com/paritytech/substrate-developer-hub/issues -->
|
||||
//! <ul>
|
||||
//! <li>Documentation comments (i.e. <code>/// comment</code>) - should accompany module functions and be restricted to the module interface, not the internals of the module implementation. Only state inputs, outputs, and a brief description that mentions whether calling it requires root, but without repeating the source code details. Capitalise 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>
|
||||
//! <!-- Original author of paragraph: @AmarRSingh -->
|
||||
//! <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 srml/example/src/lib.rs into file srml/<INSERT_CUSTOM_MODULE_NAME>/src/lib.rs of your own custom module and complete it.
|
||||
//! <details><p><pre>
|
||||
//! // Add heading with custom module name
|
||||
//!
|
||||
//! \# <INSERT_CUSTOM_MODULE_NAME> Module
|
||||
//!
|
||||
//! // Add simple description
|
||||
//!
|
||||
//! \## Overview
|
||||
//!
|
||||
//! <!-- Original author of paragraph: Various. See https://github.com/paritytech/substrate-developer-hub/issues/44 -->
|
||||
//! // Short description of module purpose.
|
||||
//! // Links to Traits that should be implemented.
|
||||
//! // What this module is for.
|
||||
//! // What functionality the module provides.
|
||||
//! // When to use the module (use case examples).
|
||||
//! // How it is used.
|
||||
//! // Inputs it uses and the source of each input.
|
||||
//! // Outputs it produces.
|
||||
//!
|
||||
//! <br>
|
||||
//!
|
||||
//! <b>Standard format (example):</b> "The timestamp module provides functionality to get and set the on-chain time.
|
||||
//! To use the timestamp module you need to implement the following [Trait] (<INSERT_LINK_TO_TRAIT>).
|
||||
//! Supported dispatchables are documented in the [Call] enum."
|
||||
//!
|
||||
//! <!-- 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 module. Include concepts, storage items, or actions that you think
|
||||
//! // deserve to be noted to give context to the rest of the documentation or module 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 module.
|
||||
//!
|
||||
//! <br>
|
||||
//!
|
||||
//! <!-- Original author of heading: @Kianenigma in PR https://github.com/paritytech/substrate/pull/1951 -->
|
||||
//!
|
||||
//! \## Goals
|
||||
//!
|
||||
//! // Add goals that the custom module 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 module.
|
||||
//! // Describe the process of interacting with the custom module for this scenario and public API functions used.
|
||||
//!
|
||||
//! \## Interface
|
||||
//!
|
||||
//! \### Supported Origins
|
||||
//!
|
||||
//! // What origins are used and supported in this module (root, signed, inherent)
|
||||
//! // i.e. root when <code>\`ensure_root\`</code> used
|
||||
//! // i.e. inherent when <code>\`ensure_inherent\`</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 module, not for specific functions.
|
||||
//! // For example, in the balances module: "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 module (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 module
|
||||
//!
|
||||
//! \### Digest Items
|
||||
//!
|
||||
//! // Explain any digest items included in this module
|
||||
//!
|
||||
//! \### Inherent Data
|
||||
//!
|
||||
//! // Explain what inherent data (if any) is defined in the module and any other related types
|
||||
//!
|
||||
//! \### Events:
|
||||
//!
|
||||
//! // Insert events for this module if any
|
||||
//!
|
||||
//! \### Errors:
|
||||
//!
|
||||
//! // Explain what generates errors
|
||||
//!
|
||||
//! \## Usage
|
||||
//!
|
||||
//! // Insert 2-3 examples of usage and code snippets that show how to use <INSERT_CUSTOM_MODULE_NAME> module in a custom module.
|
||||
//!
|
||||
//! \### Prerequisites
|
||||
//!
|
||||
//! // Show how to include necessary imports for <INSERT_CUSTOM_MODULE_NAME> and derive
|
||||
//! // your module configuration trait with the `INSERT_CUSTOM_MODULE_NAME` trait.
|
||||
//!
|
||||
//! \```rust
|
||||
//! use <INSERT_CUSTOM_MODULE_NAME>;
|
||||
//!
|
||||
//! pub trait Trait: <INSERT_CUSTOM_MODULE_NAME>::Trait { }
|
||||
//! \```
|
||||
//!
|
||||
//! \### Simple Code Snippet
|
||||
//!
|
||||
//! // Show a simple example (e.g. how to query a public getter function of <INSERT_CUSTOM_MODULE_NAME>)
|
||||
//!
|
||||
//! \### Example from SRML
|
||||
//!
|
||||
//! // 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/#/
|
||||
//!
|
||||
//! // Show a usage example in an actual runtime
|
||||
//!
|
||||
//! \## Genesis Config
|
||||
//!
|
||||
//! <!-- Original author of paragraph: @joepetrowski -->
|
||||
//!
|
||||
//! \## Dependencies
|
||||
//!
|
||||
//! // Dependencies on other SRML modules and the genesis config should be mentioned,
|
||||
//! // but not the Rust Standard Library.
|
||||
//! // Genesis configuration modifications that may be made to incorporate this module
|
||||
//! // Interaction with other modules
|
||||
//!
|
||||
//! <!-- Original author of heading: @AmarRSingh -->
|
||||
//!
|
||||
//! \## Related Modules
|
||||
//!
|
||||
//! // Interaction with other modules 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>
|
||||
|
||||
// Ensure we're `no_std` when compiling for Wasm.
|
||||
#![cfg_attr(not(feature = "std"), no_std)]
|
||||
|
||||
Reference in New Issue
Block a user