Followup test for checking propagated documentation

codegen/src/api/calls.rs

@@ -154,7 +154,11 @@ pub fn generate_calls(
         })
         .unzip();
 
+    let call_ty = type_gen.resolve_type(call.ty.id());
+    let docs = call_ty.docs();
+
     quote! {
+        #( #[doc = #docs ] )*
         pub mod calls {
             use super::root_mod;
             use super::#types_mod_ident;

codegen/src/api/events.rs

@@ -81,8 +81,11 @@ pub fn generate_events(
         }
     });
     let event_type = type_gen.resolve_type_path(event.ty.id(), &[]);
+    let event_ty = type_gen.resolve_type(event.ty.id());
+    let docs = event_ty.docs();
 
     quote! {
+        #( #[doc = #docs ] )*
         pub type Event = #event_type;
         pub mod events {
             use super::#types_mod_ident;

codegen/src/types/type_def.rs

@@ -46,6 +46,8 @@ pub struct TypeDefGen {
     derives: Derives,
     /// The kind of type to be generated.
     ty_kind: TypeDefGenKind,
+    /// Type documentation.
+    ty_docs: TokenStream,
 }
 
 impl TypeDefGen {
@@ -119,10 +121,14 @@ impl TypeDefGen {
             _ => TypeDefGenKind::BuiltIn,
         };
 
+        let docs = ty.docs();
+        let ty_docs = quote! { #( #[doc = #docs ] )* };
+
         Self {
             type_params,
             derives,
             ty_kind,
+            ty_docs,
         }
     }
 }
@@ -152,8 +158,10 @@ impl quote::ToTokens for TypeDefGen {
                 let enum_ident = format_ident!("{}", type_name);
                 let type_params = &self.type_params;
                 let derives = &self.derives;
+                let docs = &self.ty_docs;
                 let ty_toks = quote! {
                     #derives
+                    #docs
                     pub enum #enum_ident #type_params {
                         #( #variants, )*
                     }

integration-tests/Cargo.toml

@@ -20,11 +20,14 @@ codec = { package = "parity-scale-codec", version = "3.0.0", default-features =
 frame-metadata = "15.0.0"
 futures = "0.3.13"
 hex = "0.4.3"
+regex = "1.5"
 scale-info = { version = "2.0.0", features = ["bit-vec"] }
 sp-core = { version = "6.0.0", default-features = false  }
 sp-keyring = "6.0.0"
 sp-runtime = "6.0.0"
 subxt = { version = "0.21.0", path = "../subxt" }
+subxt-codegen = { version = "0.21.0", path = "../codegen" }
+syn = "1.0.58"
 test-runtime = { path = "../test-runtime" }
 tokio = { version = "1.8", features = ["macros", "time"] }
 tracing = "0.1.34"

integration-tests/src/codegen/codegen_documentation.rs

@@ -0,0 +1,119 @@
+// Copyright 2019-2022 Parity Technologies (UK) Ltd.
+// This file is part of subxt.
+//
+// subxt is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// subxt is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// You should have received a copy of the GNU General Public License
+// along with subxt.  If not, see <http://www.gnu.org/licenses/>.
+
+use regex::Regex;
+use subxt_codegen::{
+    DerivesRegistry,
+    RuntimeGenerator,
+};
+
+fn metadata_docs() -> Vec<String> {
+    // Load the runtime metadata downloaded from a node via `test-runtime`.
+    let bytes = test_runtime::METADATA;
+    let meta: frame_metadata::RuntimeMetadataPrefixed =
+        codec::Decode::decode(&mut &*bytes).expect("Cannot decode scale metadata");
+    let metadata = match meta.1 {
+        frame_metadata::RuntimeMetadata::V14(v14) => v14,
+        _ => panic!("Unsupported metadata version {:?}", meta.1),
+    };
+
+    // Inspect the metadata types and collect the documentation.
+    let mut docs = Vec::new();
+    for ty in metadata.types.types() {
+        docs.extend_from_slice(ty.ty().docs());
+    }
+
+    for pallet in metadata.pallets {
+        if let Some(storage) = pallet.storage {
+            for entry in storage.entries {
+                docs.extend(entry.docs);
+            }
+        }
+        // Note: Calls, Events and Errors are deduced directly to
+        // PortableTypes which are handled above.
+        for constant in pallet.constants {
+            docs.extend(constant.docs);
+        }
+    }
+    // Note: Extrinsics do not have associated documentation, but is implied by
+    // associated Type.
+
+    docs
+}
+
+fn generate_runtime_interface() -> String {
+    // Load the runtime metadata downloaded from a node via `test-runtime`.
+    let bytes = test_runtime::METADATA;
+    let metadata: frame_metadata::RuntimeMetadataPrefixed =
+        codec::Decode::decode(&mut &*bytes).expect("Cannot decode scale metadata");
+
+    // Generate a runtime interface form the provided metadata.
+    let generator = RuntimeGenerator::new(metadata);
+    let item_mod = syn::parse_quote!(
+        pub mod api {}
+    );
+    let derives = DerivesRegistry::default();
+    generator.generate_runtime(item_mod, derives).to_string()
+}
+
+fn interface_docs() -> Vec<String> {
+    // Generate the runtime interface from the node's metadata.
+    // Note: the API is generated on a single line.
+    let runtime_api = generate_runtime_interface();
+
+    // Documentation lines have the following format:
+    //    # [ doc = "Upward message is invalid XCM."]
+    // Given the API is generated on a single line, the regex matching
+    // must be lazy hence the `?` in the matched group `(.*?)`.
+    //
+    // The greedy `non-?` matching would lead to one single match
+    // from the beginning of the first documentation tag, containing everything up to
+    // the last documentation tag
+    // `# [ doc = "msg"] # [ doc = "msg2"] ... api ... # [ doc = "msgN" ]`
+    //
+    // The `(.*?)` stands for match any character zero or more times lazily.
+    let re = Regex::new(r#"\# \[doc = "(.*?)"\]"#).unwrap();
+    re.captures_iter(&runtime_api)
+        .filter_map(|capture| {
+            // Get the matched group (ie index 1).
+            capture.get(1).as_ref().map(|doc| {
+                // Generated documentation will escape special characters.
+                // Replace escaped characters with unescaped variants for
+                // exact matching on the raw metadata documentation.
+                doc.as_str()
+                    .replace("\\n", "\n")
+                    .replace("\\t", "\t")
+                    .replace("\\\"", "\"")
+            })
+        })
+        .collect()
+}
+
+#[test]
+fn check_documentation() {
+    // Inspect metadata recursively and obtain all associated documentation.
+    let raw_docs = metadata_docs();
+    // Obtain documentation from the generated API.
+    let runtime_docs = interface_docs();
+
+    for raw in raw_docs.iter() {
+        assert!(
+            runtime_docs.contains(raw),
+            "Documentation not present in runtime API: {}",
+            raw
+        );
+    }
+}

integration-tests/src/codegen/mod.rs

@@ -24,3 +24,5 @@
 #[rustfmt::skip]
 #[allow(clippy::all)]
 mod polkadot;
+
+mod codegen_documentation;