Crate noble_example[−][src]

Example Noble

The Example: A simple example of a FABRIC noble demonstrating concepts, APIs and structures common to most FABRIC runtimes.

Run cargo doc --package noble-example --open to view this noble’s documentation.

Documentation Guidelines:

  • Documentation comments (i.e. /// comment) - should accompany noble functions and be restricted to the noble interface, not the internals of the noble 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 fabric/example/src/lib.rs into file fabric/<INSERT_CUSTOM_NOBLE_NAME>/src/lib.rs of your own custom noble and complete it.

// Add heading with custom noble name

# <INSERT_CUSTOM_NOBLE_NAME> Noble


// Add simple description


// Include the following links that shows what trait needs to be implemented to use the noble
// and the supported dispatchables that are documented in the Call enum.


    

  • [<INSERT_CUSTOM_NOBLE_NAME>::Config](./trait.Config.html)
    • 

  • [Call](./enum.Call.html)
    • 

  • [Module](./struct.Module.html)
    • 



## Overview



// Short description of noble’s purpose.
// Links to Traits that should be implemented.
// What this noble is for.
// What functionality the noble provides.
// When to use the noble (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 noble. Include concepts, storage items, or actions that you think
// deserve to be noted to give context to the rest of the documentation or noble 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 noble.
// Please do not link to outside resources. The reference docs should be the ultimate source of truth.



## Goals


// Add goals that the custom noble is designed to achieve.



### Scenarios



#### <INSERT_SCENARIO_NAME>


// Describe requirements prior to interacting with the custom noble.
// Describe the process of interacting with the custom noble for this scenario and public API functions used.


## Interface


### Supported Origins


// What origins are used and supported in this noble (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 Tetcore 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 noble, not for specific functions.
// For example, in the Balances Noble: “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 noble (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 noble


### Digest Items


// Explain any digest items included in this noble


### Inherent Data


// Explain what inherent data (if any) is defined in the noble and any other related types


### Events:


// Insert events for this noble if any


### Errors:


// Explain what generates errors


## Usage


// Insert 2-3 examples of usage and code snippets that show how to
// use <INSERT_CUSTOM_NOBLE_NAME> Noble in a custom noble.


### Prerequisites


// Show how to include necessary imports for <INSERT_CUSTOM_NOBLE_NAME> and derive
// your noble configuration trait with the INSERT_CUSTOM_NOBLE_NAME trait.


```rust
use <INSERT_CUSTOM_NOBLE_NAME>;


pub trait Config: <INSERT_CUSTOM_NOBLE_NAME>::Config { }
```


### Simple Code Snippet


// Show a simple example (e.g. how to query a public getter function of <INSERT_CUSTOM_NOBLE_NAME>)


### Example from FABRIC


// Show a usage example in an actual runtime


// See:
// - Tetcore TCR https://github.com/tetsy-samples/tetcore-tcr
// - Tetcore Kitties https://shawntabrizi.github.io/tetcore-collectables-workshop/#/


## Genesis Config



## Dependencies


// Dependencies on other FABRIC nobles and the genesis config should be mentioned,
// but not the Rust Standard Library.
// Genesis configuration modifications that may be made to incorporate this noble
// Interaction with other nobles



## Related Nobles


// Interaction with other nobles 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.

Re-exports

pub use $crate::traits::GetNobleVersion as _;

Structs

GenesisConfig

Genesis config for the module, allow to build genesis storage.

Module
WatchDummy

A simple signed extension that checks for the set_dummy call. In that case, it increases the priority and prints some log.

Enums

Call

Dispatchable calls.

RawEvent

Events for this module.

Traits

Config

Our noble’s configuration trait. All our types and constants go in here. If the noble is dependent on specific other nobles, then their configuration traits should be added to our implied traits list.

Type Definitions

Event

RawEvent specialized for the configuration Config