diff --git a/srml/example/src/lib.rs b/srml/example/src/lib.rs index 4f4e0b96a0b62..f6f2725afe80f 100644 --- a/srml/example/src/lib.rs +++ b/srml/example/src/lib.rs @@ -14,8 +14,230 @@ // You should have received a copy of the GNU General Public License // along with Substrate. If not, see . +//! # Example Module +//! +//! //! 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: +//! +//! +//! +//! +//! ### Documentation Template:
+//! +//! Copy and paste this template from srml/example/src/lib.rs into file srml//src/lib.rs of your own custom module and complete it. +//!

+//! // Add heading with custom module name
+//!
+//! \#  Module
+//!
+//! // Add simple description
+//!
+//! \## Overview
+//!
+//!  
+//! // 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.
+//!
+//! 
+//! +//! Standard format (example): "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] (). +//! Supported dispatchables are documented in the [Call] enum." +//! +//! +//! +//! +//! \## 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. +//! +//!
+//! +//! +//! +//! \## Goals +//! +//! // Add goals that the custom module is designed to achieve. +//! +//! +//! +//! \### Scenarios +//! +//! +//! +//! \#### +//! +//! // 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 \`ensure_root\` used +//! // i.e. inherent when \`ensure_inherent\` used +//! // i.e. signed when \`ensure_signed\` used +//! +//! \`inherent\` +//! +//! +//! +//! \### Types +//! +//! // Type aliases. Include any associated types and where the user would typically define them. +//! +//! \`ExampleType\` +//! +//! +//! +//! // 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 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." +//! +//! +//! +//! // 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 +//! +//! \##### \`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 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 module in a custom module. +//! +//! \### Prerequisites +//! +//! // Show how to include necessary imports for and derive +//! // your module configuration trait with the `INSERT_CUSTOM_MODULE_NAME` trait. +//! +//! \```rust +//! use ; +//! +//! pub trait Trait: ::Trait { } +//! \``` +//! +//! \### Simple Code Snippet +//! +//! // Show a simple example (e.g. how to query a public getter function of ) +//! +//! \### 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 +//! +//! +//! +//! \## 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 +//! +//! +//! +//! \## Related Modules +//! +//! // Interaction with other modules 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. +//!

// Ensure we're `no_std` when compiling for Wasm. #![cfg_attr(not(feature = "std"), no_std)]