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 #12939.
Closes paritytech/frame-metadata#47.

// CC @paritytech/tools-team

[lexnv]

bot rebase

[paritytech-processbot]

Rebased

[sam0x17]

looks good, nice UI tests!

[sam0x17]

💯

[niklasad1]

Basti wrote

we probably should settle with having on #![doc = include_str!("../README.md")] at the top of lib.rs and then some special pallet_docs("../README.md") attribute for the frame macros (otherwise the docs would be duplicated in the crate).

Personally, I don't understand that by the documentation in this PR. Can you elaborate a bit why both doc and pallet_doc are needed in the examples or something.

It could be just me though... :)

[lexnv]

Yep, that makes sense! I've improved the documentation a bit to clarify the attributes.

From a discussion with @bkchr it would be beneficial to have:

• the ability to document the module individually and propagate that to the metadata (via doc attribute)
• the ability to only propagate documentation to the metadata only (via pallet_doc)
  • for these cases developers may use include_str!() at the top of the file without having to duplicate the documentation itself
  • pallet_doc attribute gives developers enough control until we can deduce the file from which a macro is invoked, and not the compile time location at which the macro is declared (Tracking issue for proc_macro::Span inspection APIs rust-lang/rust#54725)

[bkchr]

Here you mention that the docs are above the module and above the pallet attribute macro you are mentioning that the docs need to be above the struct Pallet,

[lexnv]

Thanks for spotting this! I've picked the pub mod pallet to be consistent between documentations and pushed the commit here 🙏

[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