Propagate documentation to runtime API

[lexnv]

This PR propagates the documentation from the metadata blob to the generated API.

The documentation is propagated to either TransactionApi or StorageApi if the inspected type is a call or storage, instead of being placed directly on the generated object.

This is done mainly to document the paths by which the user interacts with the API, as opposed to documenting the inner details of the API. For other types, the metadata documentation is set in place for the generated object.

Examples

Inherited from generated object

impl<'a, T: ::subxt::Config> StorageApi<'a, T> {
...
    #[doc = " The full account information for a particular account ID."]
    pub async fn account(

pub struct TransactionApi<'a, T: ::subxt::Config, X> {
...
    #[doc = "Anonymously schedule a task."]
    pub fn schedule(

pub struct ConstantsApi<'a, T: ::subxt::Config> {
...
    #[doc = " The maximum weight that may be scheduled per block for any dispatchables of less"]
    #[doc = " priority than `schedule::HARD_DEADLINE`."]
    pub fn maximum_weight(

Placed directly on the generated object

pub type Event = runtime_types::polkadot_runtime_common::crowdloan::pallet::Event;
  pub mod events {
    use super::runtime_types;
    #[derive(:: subxt :: codec :: Encode, :: subxt :: codec :: Decode, Debug)]
    #[doc = "Create a new crowdloaning campaign. `[fund_index]`"]
    pub struct Created(pub runtime_types::polkadot_parachain::primitives::Id);

pub type Event = runtime_types::pallet_preimage::pallet::Event;
  pub mod events {
    use super::runtime_types;
    #[derive(:: subxt :: codec :: Encode, :: subxt :: codec :: Decode, Debug)]
    #[doc = "A preimage has been noted."]
    pub struct Noted {
        pub hash: ::subxt::sp_core::H256,
    }

Closes #503 .

[niklasad1]

can you explain the why the docs for the inner call structures are "drained" and generated for the wrappers only?

[lexnv]

My initial intuition was to keep the documentation on both the calling methods and inner structures.
The user should call the exposed API and not necessarily care about the inner structures used to construct the call.

  pub struct Transfer {
   ...
      pub value: ::core::primitive::u128,
  }

  /// Doc goes here
  pub fn transfer( ... ) {
      let call = Transfer { dest, value };
      ::subxt::SubmittableExtrinsic::new(self.client, call)
  }

Although someone could potentially submit a manually constructed extrinsic (as the pub fn transfer implementation), I think this is quite uncommon.

Would you think having documentation on both would also satisfy those manually constructed cases? 🤔

[niklasad1]

Ok, I agree the outer docs should be sufficient then.

I think someone constructs their own extrinsics I guess they are on their own anyway.

[niklasad1]

Looks clean, is there a way to test that the docs are generated with a compile-time test such as #[deny(missing_docs)] or something?

[lexnv]

@niklasad1 Thanks for the feedback and review :D I don't think we could do a compile-time check with simply #[deny(missing_docs)], some Types simply would not provide documentation. However, I do believe a small script/test could be added to:

• Get metadata from runtime node
• Obtain recursively the documentation from the metadata
• Read subxt/codegen/../polkadot.rs line by line and ensure all lines from metadata are present there

[ascjones]

Awesome 👍