Metadata V15: Expose pallet documentation

[lexnv]

This patch captures the pallet documentation declared on the pallet module. The documentation added to this pallet is later on included in the runtime metadata.

The documentation can be defined in the following ways:

#[pallet::pallet]
/// Documentation for pallet 1
#[doc = "Documentation for pallet 2"]
#[doc = include_str!("../README.md")]
#[pallet_doc("../doc1.md")]
#[pallet_doc("../doc2.md")]
pub struct Pallet<T>(_);

The runtime metadata for this pallet contains the following

• " Documentation for pallet 1" (captured from ///)
• "Documentation for pallet 2" (captured from #[doc])
• content of ../README.md (captured from #[doc] with include_str!)
• content of "../doc1.md" (captured from pallet_doc)
• content of "../doc1.md" (captured from pallet_doc)

doc attribute

The value of the doc attribute is included in the runtime metadata, as well as expanded on the pallet module. The previous example is expanded to:

/// Documentation for pallet 1
/// Documentation for pallet 2
/// Content of README.md
pub struct Pallet<T>(_);

pallet_doc attribute

The pallet_doc attribute can only be provided with one argument, which is the file path that holds the documentation to be added to the metadata.

Unlike the doc attribute, the documentation provided to the proc_macro attribute is not inserted at the beginning of the module.

Testing Done

Besides the unit-test and UI tests from this patch:

• added this on top of the final metadata V15 PR (from branch https://github.com/paritytech/substrate/tree/lexnv/md15_runtime_api_v1_docs_md_bk)
• frame-metadata branch (https://github.com/paritytech/frame-metadata/tree/lexnv/md_v15_test_docs)
• subxt (https://github.com/paritytech/subxt/tree/lexnv/md_v15_bk_md_docs)

    index: 36,
    docs: [
        "# Assets Module\n\nA simple, secure module ...",
        " Hello",
    ],

Part of https://github.com/paritytech/substrate/issues/12939. Closes https://github.com/paritytech/frame-metadata/issues/47.

// CC @paritytech/tools-team

[lexnv]

bot rebase

[paritytech-processbot[bot]]

Rebased

[Polkadot-Forum]

This pull request has been mentioned on Polkadot Forum. There might be relevant details there:

https://forum.polkadot.network/t/polkadot-release-analysis-v0-9-40/2468/1

[Polkadot-Forum]

This pull request has been mentioned on Polkadot Forum. There might be relevant details there:

https://forum.polkadot.network/t/stablising-v15-metadata/2819/1