☂️ Formalize Pallet and Call docs

[ggwpez]

The FRAME team realized that Pallet and pallet Call documentation should be more formalized and probably have some templates to them.
Ultimately this can be CI checked by parsing the docs with a macro and comparing against the templates.
This should help to have a unified basis to build higher-level docs upon

First step would be to agree on a structure for the pallet level docs and README requirements for them.

(cc @lisa-parity in case you have some ideas)

[lisa-parity]

@ggwpez, this is really cool. I do have some ideas about this. I'll try. to sketch out a sample template next week.

[bkchr]

CC paritytech/frame-metadata#47

[kianenigma]

A step toward this is #13341

Right now, we have a section in the docs of some pallet that repeats the dispatchables. This should be just replaced with these modules.

[lisa-parity]

At a high level, it would be nice for every pallet to cover the following, where applicable:

• Purpose (what it's for, why it's important, the use case or problem it addresses)
• Specialized terminology (though it would be great if it wasn't required)
• Public functions
• Private functions
• How it work diagram/description
• Dependencies
• Storage items
• Events
• Errors
• Examples

I gather PR #13341 is about automating the collection of information.

[bkchr]

• Public functions

• Private functions

• Dependencies

• Storage items

• Events

• Errors

All of these don't need to be in the "high level" docs. The high level docs, as the name indicate should be a on a high level. How does the pallet work, what is it doing etc. Basically all the other things you mentioned there!

[ggwpez]

I tried out some scheme for the MQ pallet, and it basically turned into these sections. I will re-use that for the TxPause and SafeMode pallet, so please propose improvements.

• Abstract: One to three sentences about what the pallet does. Not how or why, just what.
• Design goals: Outline all specific goals of this pallet. This helps with understanding why stuff was designed in a specific way.
• Design: Explain how it is designed and why it was chosen to do so. Should reference the design goals and how they are achieved.
• Scenarios: Code examples together with explanations on how the pallet will internally process the example code. (note: examples are missing from the MQ pallet docs)
• Terminology

Diagrams would be nice, but so far i did not find a good way for ASCII diagrams or something suitable for rust doc.
Another thing missing would be the Purpose probably…

[kianenigma]

Diagrams would be nice, but so far i did not find a good way for ASCII diagrams or something suitable for rust doc.
Another thing missing would be the Purpose probably…

Have you seen mermaid? It will probably have a rendered for rust-docs.

[kianenigma]

This is my suggestion. The main alteration I have is to make the docs read from "high level" to "low level". So something like design and design goals should be all the way at the end, as this is a very low level implementation note: https://hackmd.io/4pjRqPNNTnGXJHKK9jv90A

So at a high level, it is 3 steps:

1. High Level / End-User Details (for those with least amount of knowledge)
2. Code Details (mostly for external devs, wanting to interface with the pallet, DApp builders)
3. Low Level / Implementation Details: for us, for those who want to get really deep.