From cf107727bd9171d2403475dee905ce184b062fa3 Mon Sep 17 00:00:00 2001 From: Kian Paimani <5588131+kianenigma@users.noreply.github.com> Date: Tue, 13 Jun 2023 15:33:41 +0200 Subject: [PATCH 1/5] Update DOCUMENTATION_GUIDELINES.md --- docs/DOCUMENTATION_GUIDELINES.md | 15 ++++++++++++--- 1 file changed, 12 insertions(+), 3 deletions(-) diff --git a/docs/DOCUMENTATION_GUIDELINES.md b/docs/DOCUMENTATION_GUIDELINES.md index 132c247b47ab1..5a66af31c6e6d 100644 --- a/docs/DOCUMENTATION_GUIDELINES.md +++ b/docs/DOCUMENTATION_GUIDELINES.md @@ -18,6 +18,7 @@ These are crates that are often used by external developers and need more thorou - [Polkadot and Substrate](#polkadot-and-substrate) - [Dispatchable](#dispatchable) - [Storage Items](#storage-items) + - ## General/Non-Pallet Crates @@ -222,9 +223,9 @@ Optionally, in order to demonstrate the relation between the two, you can start //! [github]: https://img.shields.io/badge/github-8da0cb?style=for-the-badge&labelColor=555555&logo=github ``` -### Dispatchable +### `#[pallet::call]` -For each dispatchable (`fn` item inside `pallet::call`), consider the following template: +For each dispatchable (`fn` item inside `#[pallet::call]`), consider the following template: ``` /// @@ -247,8 +248,16 @@ For each dispatchable (`fn` item inside `pallet::call`), consider the following pub fn name_of_dispatchable(origin: OriginFor, ...) -> DispatchResult {} ``` -### Storage Items +Consider the fact that these docs will be part of the metadata of the associated dispatchable, and might be used by wallets and explorers. + +### `#[pallet::storage]` 1. If a map-like type is being used, always note the choice of your hashers as private code docs (`// Hasher X chosen because ...`). Recall that this is not relevant information to external people, so it must be documented as `//`. 2. Consider explaining the crypto-economics of how a deposit is being taken in return of the storage being used. 3. Consider explaining why it is safe for the storage item to be unbounded, if `#[pallet::unbounded]` or `#[pallet::without_storage_info]` is being used. + +### `[pallet::error]` and `#[pallet::event]` + +Consider the fact that, similar to dispatchables, these docs will be part of the metadata of the associated event/error, and might be used by wallets and explorers. + +Specifically for `error`, explain why the errorr has happened, and what can be done in order to avoid it. From a26f6da0793dfefe5fbf6dba33c5989c90266618 Mon Sep 17 00:00:00 2001 From: kianenigma Date: Tue, 13 Jun 2023 15:36:10 +0200 Subject: [PATCH 2/5] update ToC --- docs/DOCUMENTATION_GUIDELINES.md | 37 ++++++++++++++++---------------- 1 file changed, 19 insertions(+), 18 deletions(-) diff --git a/docs/DOCUMENTATION_GUIDELINES.md b/docs/DOCUMENTATION_GUIDELINES.md index 5a66af31c6e6d..0718d11600c1e 100644 --- a/docs/DOCUMENTATION_GUIDELINES.md +++ b/docs/DOCUMENTATION_GUIDELINES.md @@ -4,21 +4,22 @@ This document is only focused on documenting parts of substrate that relates to These are crates that are often used by external developers and need more thorough documentation. These are the crates most concerned with FRAME development. -- [General/Non-Pallet Crates](#generalnon-pallet-crates) - - [What to Document?](#what-to-document) - - [Rust Docs vs. Code Comments](#rust-docs-vs-code-comments) - - [How to Document?](#how-to-document) - - [TLDR](#tldr) - - [Proc-Macros](#proc-macros) - - [Other Guidelines](#other-guidelines) - - [Document Through Code](#document-through-code) - - [Formatting Matters](#formatting-matters) -- [Pallet Crates](#pallet-crates) - - [Top Level Pallet Docs (`lib.rs`)](#top-level-pallet-docs-librs) - - [Polkadot and Substrate](#polkadot-and-substrate) - - [Dispatchable](#dispatchable) - - [Storage Items](#storage-items) - - +- [Substrate Documentation Guidelines](#substrate-documentation-guidelines) + - [General/Non-Pallet Crates](#generalnon-pallet-crates) + - [What to Document?](#what-to-document) + - [Rust Docs vs. Code Comments](#rust-docs-vs-code-comments) + - [How to Document?](#how-to-document) + - [TLDR](#tldr) + - [Proc-Macros](#proc-macros) + - [Other Guidelines](#other-guidelines) + - [Document Through Code](#document-through-code) + - [Formatting Matters](#formatting-matters) + - [Pallet Crates](#pallet-crates) + - [Top Level Pallet Docs (`lib.rs`)](#top-level-pallet-docs-librs) + - [Polkadot and Substrate](#polkadot-and-substrate) + - [`#[pallet::call]`](#palletcall) + - [`#[pallet::storage]`](#palletstorage) + - [`[pallet::error]` and `#[pallet::event]`](#palleterror-and-palletevent) ## General/Non-Pallet Crates @@ -248,7 +249,7 @@ For each dispatchable (`fn` item inside `#[pallet::call]`), consider the followi pub fn name_of_dispatchable(origin: OriginFor, ...) -> DispatchResult {} ``` -Consider the fact that these docs will be part of the metadata of the associated dispatchable, and might be used by wallets and explorers. +Consider the fact that these docs will be part of the metadata of the associated dispatchable, and might be used by wallets and explorers. ### `#[pallet::storage]` @@ -258,6 +259,6 @@ Consider the fact that these docs will be part of the metadata of the associated ### `[pallet::error]` and `#[pallet::event]` -Consider the fact that, similar to dispatchables, these docs will be part of the metadata of the associated event/error, and might be used by wallets and explorers. +Consider the fact that, similar to dispatchables, these docs will be part of the metadata of the associated event/error, and might be used by wallets and explorers. -Specifically for `error`, explain why the errorr has happened, and what can be done in order to avoid it. +Specifically for `error`, explain why the errorr has happened, and what can be done in order to avoid it. From 62626dc674393015ddf20911e8dab23dd918ffdd Mon Sep 17 00:00:00 2001 From: Kian Paimani <5588131+kianenigma@users.noreply.github.com> Date: Tue, 13 Jun 2023 19:18:01 +0200 Subject: [PATCH 3/5] Update docs/DOCUMENTATION_GUIDELINES.md Co-authored-by: Oliver Tale-Yazdi --- docs/DOCUMENTATION_GUIDELINES.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/DOCUMENTATION_GUIDELINES.md b/docs/DOCUMENTATION_GUIDELINES.md index 0718d11600c1e..5d68490ebde6f 100644 --- a/docs/DOCUMENTATION_GUIDELINES.md +++ b/docs/DOCUMENTATION_GUIDELINES.md @@ -261,4 +261,4 @@ Consider the fact that these docs will be part of the metadata of the associated Consider the fact that, similar to dispatchables, these docs will be part of the metadata of the associated event/error, and might be used by wallets and explorers. -Specifically for `error`, explain why the errorr has happened, and what can be done in order to avoid it. +Specifically for `error`, explain why the error has happened, and what can be done in order to avoid it. From ef38cdc96ab1774f53cebe4143dadd060e9b4505 Mon Sep 17 00:00:00 2001 From: Kian Paimani <5588131+kianenigma@users.noreply.github.com> Date: Tue, 13 Jun 2023 19:23:26 +0200 Subject: [PATCH 4/5] Update docs/DOCUMENTATION_GUIDELINES.md Co-authored-by: Oliver Tale-Yazdi --- docs/DOCUMENTATION_GUIDELINES.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/DOCUMENTATION_GUIDELINES.md b/docs/DOCUMENTATION_GUIDELINES.md index 5d68490ebde6f..c3462f4f2167f 100644 --- a/docs/DOCUMENTATION_GUIDELINES.md +++ b/docs/DOCUMENTATION_GUIDELINES.md @@ -19,7 +19,7 @@ These are crates that are often used by external developers and need more thorou - [Polkadot and Substrate](#polkadot-and-substrate) - [`#[pallet::call]`](#palletcall) - [`#[pallet::storage]`](#palletstorage) - - [`[pallet::error]` and `#[pallet::event]`](#palleterror-and-palletevent) + - [`#[pallet::error]` and `#[pallet::event]`](#palleterror-and-palletevent) ## General/Non-Pallet Crates From 980a3755f176eab6947dfd6b0dbc7d25ef14f67d Mon Sep 17 00:00:00 2001 From: kianenigma Date: Wed, 14 Jun 2023 08:17:40 +0100 Subject: [PATCH 5/5] fix --- docs/DOCUMENTATION_GUIDELINES.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/DOCUMENTATION_GUIDELINES.md b/docs/DOCUMENTATION_GUIDELINES.md index c3462f4f2167f..93b8672b8a4b8 100644 --- a/docs/DOCUMENTATION_GUIDELINES.md +++ b/docs/DOCUMENTATION_GUIDELINES.md @@ -17,9 +17,9 @@ These are crates that are often used by external developers and need more thorou - [Pallet Crates](#pallet-crates) - [Top Level Pallet Docs (`lib.rs`)](#top-level-pallet-docs-librs) - [Polkadot and Substrate](#polkadot-and-substrate) - - [`#[pallet::call]`](#palletcall) - - [`#[pallet::storage]`](#palletstorage) - - [`#[pallet::error]` and `#[pallet::event]`](#palleterror-and-palletevent) + - [Dispatchables](#dispatchables) + - [Storage Items](#storage-items) + - [Errors and Events](#errors-and-events) ## General/Non-Pallet Crates @@ -224,7 +224,7 @@ Optionally, in order to demonstrate the relation between the two, you can start //! [github]: https://img.shields.io/badge/github-8da0cb?style=for-the-badge&labelColor=555555&logo=github ``` -### `#[pallet::call]` +### Dispatchables For each dispatchable (`fn` item inside `#[pallet::call]`), consider the following template: @@ -251,13 +251,13 @@ pub fn name_of_dispatchable(origin: OriginFor, ...) -> DispatchResult {} Consider the fact that these docs will be part of the metadata of the associated dispatchable, and might be used by wallets and explorers. -### `#[pallet::storage]` +### Storage Items 1. If a map-like type is being used, always note the choice of your hashers as private code docs (`// Hasher X chosen because ...`). Recall that this is not relevant information to external people, so it must be documented as `//`. 2. Consider explaining the crypto-economics of how a deposit is being taken in return of the storage being used. 3. Consider explaining why it is safe for the storage item to be unbounded, if `#[pallet::unbounded]` or `#[pallet::without_storage_info]` is being used. -### `[pallet::error]` and `#[pallet::event]` +### Errors and Events Consider the fact that, similar to dispatchables, these docs will be part of the metadata of the associated event/error, and might be used by wallets and explorers.