From 6a5ad5fb48ca0600baa97d19927f804c2683c154 Mon Sep 17 00:00:00 2001 From: Luke Schoen Date: Thu, 7 Mar 2019 18:41:16 +0100 Subject: [PATCH 01/11] WIP: SRML Example Module README --- srml/example/README.adoc | 124 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 124 insertions(+) create mode 100644 srml/example/README.adoc diff --git a/srml/example/README.adoc b/srml/example/README.adoc new file mode 100644 index 0000000000000..d9ebf562c52a2 --- /dev/null +++ b/srml/example/README.adoc @@ -0,0 +1,124 @@ +// IMPORTANT NOTES: +// +// * Documentation comments (i.e. `/// comment`) - 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. +// * Documentation comments (i.e. `/// comment`) - capitalise the first word and end with a full stop +// * 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. + +// EXAMPLE CUSTOM MODULE README + +// Add custom module name +# Module + +// Simple description + +## Overview + +// Description +// 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. + +## Public 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 +* `ExampleType` - + +// IMPORTANT: 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. + +### Public Inspection functions - Immutable (getters) + +// Insert a heading 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 heading 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 examples, and code snippets for module usage + +// The following example shows how to use the module in your custom module to . + +1. Import the `INSERT_MODULE_NAME` module and derive your module configuration trait with the `INSERT_MODULE_NAME` trait. + +``` +use ; + +pub trait Trait: ::Trait { } +``` + +2. In your module call the `INSERT_MODULE_NAME` module's `example_getter_name()` function to get . + +``` +const example_value = ::Module>::example_getter_name(); +``` + +## Implementation Details + +### Module configuration trait + +// Explain implementation details that look important or distinguish the module + +The module configuration trait of the `INSERT_MODULE_NAME` module derives from the `INSERT_MODULE_NAME` module and it defines the `ExampleType` type to represent . + +### Other implemented traits + +// Explain other implementation trait details + +## Extensibility + +// Explain how to modify or customise the module to make it their own + +## Dependencies + +// Dependencies on other SRML modules +// Genesis configuration modifications that may be made to incorporate this module +// Interaction with other modules From 781c8493044761f00100fad3bc61e5337aa1b6b1 Mon Sep 17 00:00:00 2001 From: Luke Schoen Date: Thu, 7 Mar 2019 18:44:34 +0100 Subject: [PATCH 02/11] add newlines --- srml/example/README.adoc | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/srml/example/README.adoc b/srml/example/README.adoc index d9ebf562c52a2..34876e96a9bfe 100644 --- a/srml/example/README.adoc +++ b/srml/example/README.adoc @@ -1,7 +1,6 @@ // IMPORTANT NOTES: // -// * Documentation comments (i.e. `/// comment`) - 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. -// * Documentation comments (i.e. `/// comment`) - capitalise the first word and end with a full stop +// * Documentation comments (i.e. `/// comment`) - 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. Generic example of annotating source code with documentation comments: https://github.com/paritytech/substrate#72-contributing-to-documentation-for-substrate-packages // * 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`) @@ -64,9 +63,11 @@ // 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 From 5b3530e6383457b183d01b8c44ac30a8fdaccbc6 Mon Sep 17 00:00:00 2001 From: Luke Schoen Date: Fri, 8 Mar 2019 15:50:03 +0100 Subject: [PATCH 03/11] review-fix: Change const to let. Explain generic usage more --- srml/example/README.adoc | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) diff --git a/srml/example/README.adoc b/srml/example/README.adoc index 34876e96a9bfe..e5dbc6bd29242 100644 --- a/srml/example/README.adoc +++ b/srml/example/README.adoc @@ -84,10 +84,9 @@ ## Usage -// Insert examples, and code snippets for module usage - -// The following example shows how to use the module in your custom module to . +// Insert examples and code snippets that show how to use module in a custom module. +// Show how to import 1. Import the `INSERT_MODULE_NAME` module and derive your module configuration trait with the `INSERT_MODULE_NAME` trait. ``` @@ -96,10 +95,18 @@ use ; pub trait Trait: ::Trait { } ``` -2. In your module call the `INSERT_MODULE_NAME` module's `example_getter_name()` function to get . +// Show how to query a public getter functions of +2. Query the `INSERT_MODULE_NAME` module's `example_getter_name()`. + +``` +let queried_value = >::example_getter_name(); +``` + +// Show how to call a public setter function to change state using +2. Change state using `INSERT_MODULE_NAME` module's `example_setter_name()`. ``` -const example_value = ::Module>::example_getter_name(); +>::example_setter_name(); ``` ## Implementation Details @@ -120,6 +127,6 @@ The module configuration trait of the `INSERT_MODULE_NAME` module derives from t ## Dependencies -// Dependencies on other SRML modules +// Dependencies on other SRML modules should be mentioned, but not the Rust Standard Library // Genesis configuration modifications that may be made to incorporate this module // Interaction with other modules From 9dc0c4011c1ef8aba44b155858e413d052c19565 Mon Sep 17 00:00:00 2001 From: Luke Schoen Date: Mon, 11 Mar 2019 12:01:51 +0100 Subject: [PATCH 04/11] refactor: Remove example steps 2 and 3. User can refer to other examples to figure it out --- srml/example/README.adoc | 14 +------------- 1 file changed, 1 insertion(+), 13 deletions(-) diff --git a/srml/example/README.adoc b/srml/example/README.adoc index e5dbc6bd29242..b5038603039f1 100644 --- a/srml/example/README.adoc +++ b/srml/example/README.adoc @@ -95,19 +95,7 @@ use ; pub trait Trait: ::Trait { } ``` -// Show how to query a public getter functions of -2. Query the `INSERT_MODULE_NAME` module's `example_getter_name()`. - -``` -let queried_value = >::example_getter_name(); -``` - -// Show how to call a public setter function to change state using -2. Change state using `INSERT_MODULE_NAME` module's `example_setter_name()`. - -``` ->::example_setter_name(); -``` +// Show how to query a public getter and setter functions of ## Implementation Details From 968ef576e86acc022429403e378338ee9efd5611 Mon Sep 17 00:00:00 2001 From: Luke Schoen Date: Thu, 14 Mar 2019 13:05:37 +0100 Subject: [PATCH 05/11] fix: Update to incorporate approved approach of staking module docs in PR #1951 --- srml/example/README.adoc | 120 ---------------------- srml/example/src/lib.rs | 217 ++++++++++++++++++++++++++++++++++++++- 2 files changed, 216 insertions(+), 121 deletions(-) delete mode 100644 srml/example/README.adoc diff --git a/srml/example/README.adoc b/srml/example/README.adoc deleted file mode 100644 index b5038603039f1..0000000000000 --- a/srml/example/README.adoc +++ /dev/null @@ -1,120 +0,0 @@ -// IMPORTANT NOTES: -// -// * Documentation comments (i.e. `/// comment`) - 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. Generic example of annotating source code with documentation comments: https://github.com/paritytech/substrate#72-contributing-to-documentation-for-substrate-packages -// * 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. - -// EXAMPLE CUSTOM MODULE README - -// Add custom module name -# Module - -// Simple description - -## Overview - -// Description -// 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. - -## Public 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 -* `ExampleType` - - -// IMPORTANT: 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. - -### Public Inspection functions - Immutable (getters) - -// Insert a heading 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 heading 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 examples and code snippets that show how to use module in a custom module. - -// Show how to import -1. Import the `INSERT_MODULE_NAME` module and derive your module configuration trait with the `INSERT_MODULE_NAME` trait. - -``` -use ; - -pub trait Trait: ::Trait { } -``` - -// Show how to query a public getter and setter functions of - -## Implementation Details - -### Module configuration trait - -// Explain implementation details that look important or distinguish the module - -The module configuration trait of the `INSERT_MODULE_NAME` module derives from the `INSERT_MODULE_NAME` module and it defines the `ExampleType` type to represent . - -### Other implemented traits - -// Explain other implementation trait details - -## Extensibility - -// Explain how to modify or customise the module to make it their own - -## Dependencies - -// Dependencies on other SRML modules should be mentioned, but not the Rust Standard Library -// Genesis configuration modifications that may be made to incorporate this module -// Interaction with other modules diff --git a/srml/example/src/lib.rs b/srml/example/src/lib.rs index 4f4e0b96a0b62..93b1def442bdc 100644 --- a/srml/example/src/lib.rs +++ b/srml/example/src/lib.rs @@ -14,8 +14,223 @@ // 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. +//! concepts, APIs and structures common to most runtime modules. +//! +//! ### Documentation Guidelines: +//! +//! +//! * Documentation comments (i.e. `/// comment`) - 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. Generic example of annotating source code with documentation comments: https://github.com/paritytech/substrate#72-contributing-to-documentation-for-substrate-packages +//! * 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: +//! +//! // Add 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] (//links to the 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 (wrt 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. +//! // +//! // 1. Include 1 simple example, e.g. calling a getter +//! // 2. Include 1 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 how to import +//! // 1. Import the `INSERT_MODULE_NAME` module and derive your module configuration trait with the `INSERT_MODULE_NAME` trait. +//! +//! ``` +//! use ; +//! +//! pub trait Trait: ::Trait { } +//! ``` +//! +//! // 2. Show how to query a public getter function of +//! +//! // 3. Show a usage example in an actual runtime +//! +//! ### Prerequisites +//! +//! // Include necessary imports +//! +//! ### Simple Code Snippet +//! +//! ### Example from SRML +//! +//! ## Implementation Details +//! +//! ### Module configuration trait +//! +//! // Explain implementation details that look important or distinguish the module +//! +//! The module configuration trait of the `INSERT_MODULE_NAME` module derives from the `INSERT_MODULE_NAME` module and it defines the `ExampleType` type to represent . +//! +//! ### Other implemented traits +//! +//! // Explain other implementation trait details +//! +//! ## Extensibility +//! +//! // Explain how to modify or customise the module to make it their own +//! +//! ## 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)] From 37a1b3b1c5e94393a77b6c0d1bfc53e03b829971 Mon Sep 17 00:00:00 2001 From: Luke Schoen Date: Thu, 14 Mar 2019 15:46:23 +0100 Subject: [PATCH 06/11] fix: Move into expandable Details arrow and fix syntax so appears correctly in rust docs --- srml/example/src/lib.rs | 179 +++++++++++++++++++++++----------------- 1 file changed, 103 insertions(+), 76 deletions(-) diff --git a/srml/example/src/lib.rs b/srml/example/src/lib.rs index 93b1def442bdc..67fa3bbb82a02 100644 --- a/srml/example/src/lib.rs +++ b/srml/example/src/lib.rs @@ -18,47 +18,57 @@ //! //! //! The Example: A simple example of a runtime module demonstrating -//! concepts, APIs and structures common to most runtime modules. +//! 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 comments (i.e. `/// comment`) - 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. Generic example of annotating source code with documentation comments: https://github.com/paritytech/substrate#72-contributing-to-documentation-for-substrate-packages -//! * 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 comments (i.e. /// comment) - 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 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: +//! ### Documentation Template:
//! -//! // Add custom module name -//! # Module -//! -//! Add simple description -//! -//! ## Overview +//! 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
+//! // 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)
+//! // 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] (//links to the trait).
+//! 

+//!
+//! 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
+//!
+//! \## 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
@@ -66,76 +76,88 @@
 //! // 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
+//!
+//! \## Goals
 //!
 //! // Add goals that the custom module is designed to achieve.
 //!
 //! 
-//! ### Scenarios
-//! 
+//!
+//! \### 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
+//! \## 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 - 
+//! // i.e. root when \`ensure_root\` used
+//! // i.e. inherent when \`ensure_inherent\` used
+//! // i.e. signed when \`ensure_signed\` used
+//!
+//! \`inherent\` 
 //!
 //! 
-//! ### Types
-//! 
+//!
+//! \### Types
+//!
 //! // Type aliases. Include any associated types and where the user would typically define them.
-//! * `ExampleType` - 
-//! 
+//!
+//! \`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
+//! \### 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
+//! // MUST have link to Call enum
+//! // MUST have origin information included in function doc
+//! // CAN have more info up to the user
 //!
-//! ### Public Functions
+//! \### 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 (wrt how much information to provide).
 //!
-//! #### Public Inspection functions - Immutable (getters)
+//! // 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()`
+//! \##### \`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)
+//! \#### Public Mutable functions (changing state)
 //!
 //! // Insert a subheading for each setter function signature
 //!
-//! ##### `example_setter_name(origin, parameter_name: T::ExampleType)`
+//! \##### \`example_setter_name(origin, parameter_name: T::ExampleType)\`
 //!
 //! // What state it changes
 //! // Why, when, and how often to call it
@@ -143,78 +165,80 @@
 //! // When safety issues to consider
 //! // What parameter values are valid and why
 //!
-//! ### Storage Items
+//! \### Storage Items
 //!
 //! // Explain any storage items included in this module
 //!
-//! ### Digest Items
+//! \### Digest Items
 //!
 //! // Explain any digest items included in this module
 //!
-//! ### Inherent Data
+//! \### Inherent Data
 //!
 //! // Explain what inherent data (if any) is defined in the module and any other related types
 //!
-//! ### Events:
+//! \### Events:
 //!
 //! // Insert events for this module if any
 //!
-//! ### Errors:
+//! \### Errors:
 //!
 //! // Explain what generates errors
 //!
-//! ## Usage
+//! \## Usage
 //!
-//! // Insert 2-3 examples of usage and code snippets that show how to use  module in a custom module.
+//! // Insert 2-3 examples of usage and code snippets that show how to use  module in a custom module.
 //! //
 //! // 1. Include 1 simple example, e.g. calling a getter
 //! // 2. Include 1 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/#/
+//! // - Substrate TCR https://github.com/parity-samples/substrate-tcr
+//! // - Substrate Kitties https://shawntabrizi.github.io/substrate-collectables-workshop/#/
 //!
-//! // Show how to import 
-//! // 1. Import the `INSERT_MODULE_NAME` module and derive your module configuration trait with the `INSERT_MODULE_NAME` trait.
+//! // Show how to import 
 //!
-//! ```
-//! use ;
+//! // 1. Import the `INSERT_CUSTOM_MODULE_NAME` module and derive your module configuration trait with the `INSERT_CUSTOM_MODULE_NAME` trait.
+//!
+//! \```rust
+//! use ;
 //! 
-//! pub trait Trait: ::Trait { }
-//! ```
+//! pub trait Trait: ::Trait { }
+//! \```
 //!
-//! // 2. Show how to query a public getter function of 
+//! // 2. Show how to query a public getter function of 
 //!
 //! // 3. Show a usage example in an actual runtime
 //!
-//! ### Prerequisites
+//! \### Prerequisites
 //!
 //! // Include necessary imports
 //!
-//! ### Simple Code Snippet
+//! \### Simple Code Snippet
 //!
-//! ### Example from SRML
+//! \### Example from SRML
 //!
-//! ## Implementation Details
+//! \## Implementation Details
 //!
-//! ### Module configuration trait
+//! \### Module configuration trait
 //!
 //! // Explain implementation details that look important or distinguish the module
 //!
-//! The module configuration trait of the `INSERT_MODULE_NAME` module derives from the `INSERT_MODULE_NAME` module and it defines the `ExampleType` type to represent .
+//! The module configuration trait of the `INSERT_CUSTOM_MODULE_NAME` module derives from the `INSERT_CUSTOM_MODULE_NAME` module and it defines the `ExampleType` type to represent .
 //!
-//! ### Other implemented traits
+//! \### Other implemented traits
 //!
 //! // Explain other implementation trait details
 //!
-//! ## Extensibility
+//! \## Extensibility
 //!
 //! // Explain how to modify or customise the module to make it their own
 //!
-//! ## Genesis Config
+//! \## Genesis Config
 //!
 //! 
-//! ## Dependencies
+//!
+//! \## Dependencies
 //!
 //! // Dependencies on other SRML modules and the genesis config should be mentioned,
 //! // but not the Rust Standard Library.
@@ -222,15 +246,18 @@
 //! // Interaction with other modules
 //!
 //! 
-//! ## Related Modules
+//!
+//! \## Related Modules
 //!
 //! // Interaction with other modules in the form of a bullet point list
 //!
-//! ## References
+//! \## 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)] From aa07ade183d870aec102a0a3231eb383675e111e Mon Sep 17 00:00:00 2001 From: Luke Schoen Date: Thu, 14 Mar 2019 15:49:20 +0100 Subject: [PATCH 07/11] fix: Fix linting --- srml/example/src/lib.rs | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/srml/example/src/lib.rs b/srml/example/src/lib.rs index 67fa3bbb82a02..798efd1e5df8d 100644 --- a/srml/example/src/lib.rs +++ b/srml/example/src/lib.rs @@ -26,15 +26,15 @@ //! //! //!
    -//!
  • Documentation comments (i.e. /// comment) - 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 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 comments (i.e. /// comment) - 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 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:
From 371a8ccbe5bd270f017fcd37b4114228b104aa2b Mon Sep 17 00:00:00 2001 From: Luke Schoen Date: Fri, 15 Mar 2019 01:36:29 +0100 Subject: [PATCH 08/11] docs: Add Public Dispatchable functions --- srml/example/src/lib.rs | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/srml/example/src/lib.rs b/srml/example/src/lib.rs index 798efd1e5df8d..cee68ef8d1240 100644 --- a/srml/example/src/lib.rs +++ b/srml/example/src/lib.rs @@ -142,6 +142,10 @@ //! //! // It is up to the writer of the respective module (with respect to how much information to provide). //! +//! \#### Public Dispatchable functions +//! +//! +//! //! \#### Public Inspection functions - Immutable (getters) //! //! // Insert a subheading for each getter function signature From 16e32d73c6ec6a0c13220b32d6a9514198fbc63a Mon Sep 17 00:00:00 2001 From: Luke Schoen Date: Fri, 15 Mar 2019 01:44:26 +0100 Subject: [PATCH 09/11] fix: Rearrange to use Simple Code Snippet and Examples from SRML --- srml/example/src/lib.rs | 26 +++++++++++--------------- 1 file changed, 11 insertions(+), 15 deletions(-) diff --git a/srml/example/src/lib.rs b/srml/example/src/lib.rs index cee68ef8d1240..1121d6f43e12f 100644 --- a/srml/example/src/lib.rs +++ b/srml/example/src/lib.rs @@ -192,17 +192,11 @@ //! \## Usage //! //! // Insert 2-3 examples of usage and code snippets that show how to use module in a custom module. -//! // -//! // 1. Include 1 simple example, e.g. calling a getter -//! // 2. Include 1 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 how to import +//! \### Prerequisites //! -//! // 1. Import the `INSERT_CUSTOM_MODULE_NAME` module and derive your module configuration trait with the `INSERT_CUSTOM_MODULE_NAME` trait. +//! // Show how to include necessary imports for and derive +//! // your module configuration trait with the `INSERT_CUSTOM_MODULE_NAME` trait. //! //! \```rust //! use ; @@ -210,17 +204,19 @@ //! pub trait Trait: ::Trait { } //! \``` //! -//! // 2. Show how to query a public getter function of +//! \### Simple Code Snippet //! -//! // 3. Show a usage example in an actual runtime +//! // Show a simple example (e.g. how to query a public getter function of ) //! -//! \### Prerequisites +//! \### Example from SRML //! -//! // Include necessary imports +//! // Show a usage example in an actual runtime //! -//! \### Simple Code Snippet +//! // See: +//! // - Substrate TCR https://github.com/parity-samples/substrate-tcr +//! // - Substrate Kitties https://shawntabrizi.github.io/substrate-collectables-workshop/#/ //! -//! \### Example from SRML +//! // Show a usage example in an actual runtime //! //! \## Implementation Details //! From 7864a3b2c8bce3d7503f6a5358c27693fde78aea Mon Sep 17 00:00:00 2001 From: Luke Schoen Date: Fri, 15 Mar 2019 01:47:02 +0100 Subject: [PATCH 10/11] fix: Remove duplicate Dispatchable Functions section --- srml/example/src/lib.rs | 4 ---- 1 file changed, 4 deletions(-) diff --git a/srml/example/src/lib.rs b/srml/example/src/lib.rs index 1121d6f43e12f..0854b477b04f7 100644 --- a/srml/example/src/lib.rs +++ b/srml/example/src/lib.rs @@ -142,10 +142,6 @@ //! //! // It is up to the writer of the respective module (with respect to how much information to provide). //! -//! \#### Public Dispatchable functions -//! -//! -//! //! \#### Public Inspection functions - Immutable (getters) //! //! // Insert a subheading for each getter function signature From 2d96ac006eef2f8afe0132a0b84d079844fe2840 Mon Sep 17 00:00:00 2001 From: Luke Schoen Date: Fri, 15 Mar 2019 01:48:16 +0100 Subject: [PATCH 11/11] fix: Remove Implementation Details as requested by Gav --- srml/example/src/lib.rs | 16 ---------------- 1 file changed, 16 deletions(-) diff --git a/srml/example/src/lib.rs b/srml/example/src/lib.rs index 0854b477b04f7..f6f2725afe80f 100644 --- a/srml/example/src/lib.rs +++ b/srml/example/src/lib.rs @@ -214,22 +214,6 @@ //! //! // Show a usage example in an actual runtime //! -//! \## Implementation Details -//! -//! \### Module configuration trait -//! -//! // Explain implementation details that look important or distinguish the module -//! -//! The module configuration trait of the `INSERT_CUSTOM_MODULE_NAME` module derives from the `INSERT_CUSTOM_MODULE_NAME` module and it defines the `ExampleType` type to represent . -//! -//! \### Other implemented traits -//! -//! // Explain other implementation trait details -//! -//! \## Extensibility -//! -//! // Explain how to modify or customise the module to make it their own -//! //! \## Genesis Config //! //!