Propagate documentation to runtime API (#511)

* codegen: Propagate documentation for Constants

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* subxt: Update polkadot.rs

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* codegen: Propagate documentation for `CompositeDef` wrapper

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* subxt: Update polkadot.rs

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* codegen: Propagate docs for enum variant of `CompositeDef` wrapper

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* subxt: Update polkadot.rs

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* codegen: Propagate docs for Storage entries

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* subxt: Update polkadot.rs

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* codegen: Move docs from internal structs to methods of StorageApi

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* codegen: Propagate the same docs for storage iter variants

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* codegen: Move docs from call structs to methods of TransactionApi

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

* subxt: Update polkadot.rs

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>

codegen/src/api/calls.rs

@@ -40,14 +40,14 @@ pub fn generate_calls(
     call: &PalletCallMetadata<PortableForm>,
     types_mod_ident: &syn::Ident,
 ) -> TokenStream2 {
-    let struct_defs = super::generate_structs_from_variants(
+    let mut struct_defs = super::generate_structs_from_variants(
         type_gen,
         call.ty.id(),
         |name| name.to_upper_camel_case().into(),
         "Call",
     );
     let (call_structs, call_fns): (Vec<_>, Vec<_>) = struct_defs
-        .iter()
+        .iter_mut()
         .map(|struct_def| {
             let (call_fn_args, call_args): (Vec<_>, Vec<_>) =
                 match struct_def.fields {
@@ -78,6 +78,10 @@ pub fn generate_calls(
             let function_name = struct_def.name.to_string().to_snake_case();
             let fn_name = format_ident!("{}", function_name);
 
+            // Propagate the documentation just to `TransactionApi` methods, while
+            // draining the documentation of inner call structures.
+            let docs = struct_def.docs.take();
+            // The call structure's documentation was stripped above.
             let call_struct = quote! {
                 #struct_def
 
@@ -87,6 +91,7 @@ pub fn generate_calls(
                 }
             };
             let client_fn = quote! {
+                #docs
                 pub fn #fn_name(
                     &self,
                     #( #call_fn_args, )*

codegen/src/api/constants.rs

@@ -38,8 +38,10 @@ pub fn generate_constants(
         let pallet_name = &pallet.name;
         let constant_name = &constant.name;
         let return_ty = type_gen.resolve_type_path(constant.ty.id(), &[]);
+        let docs = &constant.docs;
 
         quote! {
+            #( #[doc = #docs ] )*
             pub fn #fn_name(&self) -> ::core::result::Result<#return_ty, ::subxt::BasicError> {
                 let pallet = self.client.metadata().pallet(#pallet_name)?;
                 let constant = pallet.constant(#constant_name)?;

codegen/src/api/mod.rs

@@ -412,6 +412,7 @@ where
                     fields,
                     Some(parse_quote!(pub)),
                     type_gen,
+                    var.docs(),
                 )
             })
             .collect()

codegen/src/api/storage.rs

@@ -248,8 +248,11 @@ fn generate_storage_entry_fns(
         }
     };
 
+    let docs = &storage_entry.docs;
+    let docs_token = quote! { #( #[doc = #docs ] )* };
     let client_iter_fn = if matches!(storage_entry.ty, StorageEntryType::Map { .. }) {
         quote! (
+            #docs_token
             pub async fn #fn_name_iter(
                 &self,
                 hash: ::core::option::Option<T::Hash>,
@@ -271,7 +274,9 @@ fn generate_storage_entry_fns(
         };
         quote!( #field_name: #reference #field_ty )
     });
+
     let client_fns = quote! {
+        #docs_token
         pub async fn #fn_name(
             &self,
             #( #key_args, )*

codegen/src/types/composite_def.rs

@@ -45,6 +45,8 @@ pub struct CompositeDef {
     pub kind: CompositeDefKind,
     /// The fields of the type, which are either all named or all unnamed.
     pub fields: CompositeDefFields,
+    /// Documentation of the composite type as presented in metadata.
+    pub docs: Option<TokenStream>,
 }
 
 impl CompositeDef {
@@ -55,6 +57,7 @@ impl CompositeDef {
         fields_def: CompositeDefFields,
         field_visibility: Option<syn::Visibility>,
         type_gen: &TypeGenerator,
+        docs: &[String],
     ) -> Self {
         let mut derives = type_gen.derives().clone();
         let fields: Vec<_> = fields_def.field_types().collect();
@@ -85,6 +88,7 @@ impl CompositeDef {
         }
 
         let name = format_ident!("{}", ident);
+        let docs_token = Some(quote! { #( #[doc = #docs ] )* });
 
         Self {
             name,
@@ -94,16 +98,23 @@ impl CompositeDef {
                 field_visibility,
             },
             fields: fields_def,
+            docs: docs_token,
         }
     }
 
     /// Construct a definition which will generate code for an `enum` variant.
-    pub fn enum_variant_def(ident: &str, fields: CompositeDefFields) -> Self {
+    pub fn enum_variant_def(
+        ident: &str,
+        fields: CompositeDefFields,
+        docs: &[String],
+    ) -> Self {
         let name = format_ident!("{}", ident);
+        let docs_token = Some(quote! { #( #[doc = #docs ] )* });
         Self {
             name,
             kind: CompositeDefKind::EnumVariant,
             fields,
+            docs: docs_token,
         }
     }
 }
@@ -111,6 +122,7 @@ impl CompositeDef {
 impl quote::ToTokens for CompositeDef {
     fn to_tokens(&self, tokens: &mut TokenStream) {
         let name = &self.name;
+        let docs = &self.docs;
 
         let decl = match &self.kind {
             CompositeDefKind::Struct {
@@ -130,6 +142,7 @@ impl quote::ToTokens for CompositeDef {
 
                 quote! {
                     #derives
+                    #docs
                     pub struct #name #type_params #fields #trailing_semicolon
                 }
             }
@@ -137,6 +150,7 @@ impl quote::ToTokens for CompositeDef {
                 let fields = self.fields.to_enum_variant_field_tokens();
 
                 quote! {
+                    #docs
                     #name #fields
                 }
             }

codegen/src/types/type_def.rs

@@ -90,6 +90,7 @@ impl<'a> TypeDefGen<'a> {
                     fields,
                     Some(parse_quote!(pub)),
                     type_gen,
+                    ty.docs(),
                 );
                 TypeDefGenKind::Struct(composite_def)
             }
@@ -107,7 +108,7 @@ impl<'a> TypeDefGen<'a> {
                         );
                         type_params.update_unused(fields.field_types());
                         let variant_def =
-                            CompositeDef::enum_variant_def(v.name(), fields);
+                            CompositeDef::enum_variant_def(v.name(), fields, v.docs());
                         (v.index(), variant_def)
                     })
                     .collect();