SRML Documentation Template

[shawntabrizi]

We need to create a markdown template for SRML documentation

MUST: Include all of these sections/subsections

Overview

• short description of module purpose
• links to [Traits], [Call], [Module]

standard format (example):

The timestamp module provides functionality to get and set the on-chain time.

See also: [Trait] [Call] [Module]

Interface

Dispatchable

MUST: Have link to Call enum
MUST: Have origin information included in function doc
CAN: Have more info up to the user

Public

up to writer for respective module (wrt how much information to provide)

Usage

Prerequisites

necessary imports

Simple Code Snippet

Example from SRML

Genesis Config

Related Modules

bulleted list to other modules (maybe one sentence)

References

[shawntabrizi]

@gautamdhameja How does something like this sound:

• Introduction
  • The purpose of the module as 1-2 paragraphs
• How to use
  • Explain how users (or system processes) use and interact with this module
  • Common call patterns
• Core Logic and Assumptions
  • Basically talk about implementation details that look important or distinguish our module
  • These might be details that the user can modify or customize to make their own
• Interactions with other SRML
• Links to other associated module documentation pages

[kianenigma]

^^ Looks pretty close to what I had in mind. Will go with this for now. If you throw in here an example of of @gautamdhameja 's docs with this structure, it will be also helpful.

[gautamdhameja]

@shawntabrizi yes, something on the same lines but a bit more detailed (so that all module docs have a similar structure). Here's what I think.

Module name

// Simple description

Overview

// description
// what this module is for
// what it provides
// when to use it - use case examples

Public Interface

// what are the public functions exposed by this module and for each function we should have,
// description of function - what it does
// signature - input params
// events
// errors

Usage

// examples, code snippets for module usage

Implementation details

// implementation details that look important or distinguish our module

Extensibility

// Details that the user can modify or customize to make their own

Dependencies

// Dependencies on other SRML modules
// Genesis config
// Interaction with other modules

Further information

// links to other docs, relevant GitHub issues and other information

[shawntabrizi]

@gautamdhameja I like it a lot. The harder question I have is what we talked about regarding splitting docs between Rust Docs and written stuff.

Things like public interface and usage seem like things that should live in the rust docs. Question would be "Can we automagically get/generate this data so that it is seamless/easy to keep things in sync?"

Furthermore how can we ensure that users know to look in the rust docs for this kind of details?

Furthermore how do we make sure stuff is searchable and discoverable?

[gautamdhameja]

I had the exact same question in mind. I agree that the public interface and usage should live with the code in Rust docs. @ltfschoen also suggested the same.
We can either embed the static html produced by rustdoc or we can link to where it will be hosted (crates.parity.io, I guess). I would prefer linking.
https://doc.rust-lang.org/rustdoc/what-is-rustdoc.html

[shawntabrizi]

Yeah, but maybe also we can try and automate some copy and paste blob that is generated from the rust docs such that we can also have some amount of content on the markdown page so it is searchable from the main readme site

[gautamdhameja]

Sure, we can. But I'd say let's focus on the content creation for now. We can have some automation tools/scripts later to improve the content presentation.

[kianenigma]

I'm definitely in favor of not having a full (or even partial) list of public functions in an .md doc. This will be a pure duplicate and makes the page look much longer.

What I've been doing so far for one of the docs is to have the overview section explain verbally some of the common scenarios that can happen withing and using the module, and I'm planning to bombard it as much as possible with links to associated rustdoc functions.

[gautamdhameja]

We had a brief review with Gav on the SRML docs template and he suggested some additional items. Here's the updated one,

Module name

// Simple description

Overview

// description
// what this module is for
// what it provides
// when to use it

Public Interface

Public Immutable functions

• description
• signature
• errors

Public Mutable functions

• description
• signature
• errors

Storage Items

// public storage items for this module

Digest Items

// digest items for this module

Inherent Data (if any)

// inherent data and other related types for this module

Events

// events for this module

Usage

// examples, code snippets for module usage

Extensibility

// Details that the user can modify or customize to make their own

Dependencies

// Dependencies on other SRML modules
// Genesis config
// Interaction with other modules

[kianenigma]

Looks good but trying to stick to this has been quite hard for at least for a relatively fat module (staking) with tens of mutable and more immutable functions. I think at least in the first draft we should be a bit flexible (same structure, every author has room to change it based on the needs.) a bit and gradually try and give them all the same structure.

and I think it is giving a bit too much weight in favor of the .md file which is in contrast of the recent conclusion to do the exact opposite: put as much docs as possible in the rust code.

[gautamdhameja]

I agree with you @kianenigma. We need to be flexible with this as all modules are somewhat different from each other. This template should be treated as general guidance only. The ultimate goal is to have informative and clear docs and if it requires us to deviate a bit from the template then that should be fine.

[shawntabrizi]

From @joepetrowski

Docs Template

Overview

Short paragraph about the purpose of the module.

Terminology

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.

Public Interface

Types

Any associated types and where the user would typically define them.

Dispatchable Functions

A brief description of dispatchable functions and a link to the rustdoc with their actual documentation.

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

Usage

2-3 examples of usage.

• 1 simple, e.g. calling a getter
• 1 usage in an actual runtime example (see TCR or Kitties)

Dependencies

Dependencies on other modules and genesis config, if applicable.

References

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

[4meta5]

MUST: Include all of these sections/subsections

Overview

• short description of module purpose
• links to Traits that should be implemented

standard format (example): "The timestamp module provides functionality to get and set the on-chain time. For using the timestamp module you need to implement the following [Trait] (//links to the trait). Supported dispatchables are documented in the [Call] enum."

Interface

Dispatchable

MUST: Have link to Call enum
MUST: Have origin information included in function doc
CAN: Have more info up to the user

Public

up to writer for respective module (wrt how much information to provide)

Usage

Prerequisites

necessary imports

Simple Code Snippet

Example from SRML

Genesis Config

Related Modules

bulleted list to other modules (maybe one sentence)

References

[shawntabrizi]

Template is tentatively finalized.

[ltfschoen]

FYI, note that I'm in the process of incorporating this template into paritytech/substrate#1947