codegen: Opt out of documentation (#843)

* codegen: Opt-out for API documentation

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

* cli: Add `--no-docs` flag

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

* tests: Check no documentation was generated

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

* Update cargo.lock

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

* tests: Adjust testing for the new codegen API

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

* macro: Ensure `subxt` macro does not contain documentation

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

* macro: Expose documentation flag

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

* expose_documentation => generate_docs

---------

Signed-off-by: Alexandru Vasile <alexandru.vasile@parity.io>
Co-authored-by: James Wilson <james@jsdw.me>

codegen/src/api/calls.rs

@@ -40,6 +40,7 @@ pub fn generate_calls(
     pallet: &PalletMetadata<PortableForm>,
     types_mod_ident: &syn::Ident,
     crate_path: &CratePath,
+    should_gen_docs: bool,
 ) -> TokenStream2 {
     // Early return if the pallet has no calls.
     let call = if let Some(ref calls) = pallet.calls {
@@ -54,6 +55,7 @@ pub fn generate_calls(
         |name| name.to_upper_camel_case().into(),
         "Call",
         crate_path,
+        should_gen_docs,
     );
     let (call_structs, call_fns): (Vec<_>, Vec<_>) = struct_defs
         .iter_mut()
@@ -98,7 +100,8 @@ pub fn generate_calls(
             let fn_name = format_ident!("{}", variant_name.to_snake_case());
             // Propagate the documentation just to `TransactionApi` methods, while
             // draining the documentation of inner call structures.
-            let docs = struct_def.docs.take();
+            let docs = should_gen_docs.then_some(struct_def.docs.take()).flatten();
+
             // The call structure's documentation was stripped above.
             let call_struct = quote! {
                 #struct_def
@@ -124,9 +127,12 @@ pub fn generate_calls(
 
     let call_ty = type_gen.resolve_type(call.ty.id());
     let docs = call_ty.docs();
+    let docs = should_gen_docs
+        .then_some(quote! { #( #[doc = #docs ] )* })
+        .unwrap_or_default();
 
     quote! {
-        #( #[doc = #docs ] )*
+        #docs
         pub mod calls {
             use super::root_mod;
             use super::#types_mod_ident;

codegen/src/api/constants.rs

@@ -48,6 +48,7 @@ pub fn generate_constants(
     pallet: &PalletMetadata<PortableForm>,
     types_mod_ident: &syn::Ident,
     crate_path: &CratePath,
+    should_gen_docs: bool,
 ) -> TokenStream2 {
     // Early return if the pallet has no constants.
     if pallet.constants.is_empty() {
@@ -64,9 +65,12 @@ pub fn generate_constants(
 
         let return_ty = type_gen.resolve_type_path(constant.ty.id());
         let docs = &constant.docs;
+        let docs = should_gen_docs
+            .then_some(quote! { #( #[doc = #docs ] )* })
+            .unwrap_or_default();
 
         quote! {
-            #( #[doc = #docs ] )*
+            #docs
             pub fn #fn_name(&self) -> #crate_path::constants::StaticConstantAddress<#crate_path::metadata::DecodeStaticType<#return_ty>> {
                 #crate_path::constants::StaticConstantAddress::new(
                     #pallet_name,

codegen/src/api/events.rs

@@ -45,6 +45,7 @@ pub fn generate_events(
     pallet: &PalletMetadata<PortableForm>,
     types_mod_ident: &syn::Ident,
     crate_path: &CratePath,
+    should_gen_docs: bool,
 ) -> TokenStream2 {
     // Early return if the pallet has no events.
     let event = if let Some(ref event) = pallet.event {
@@ -59,6 +60,7 @@ pub fn generate_events(
         |name| name.into(),
         "Event",
         crate_path,
+        should_gen_docs,
     );
     let event_structs = struct_defs.iter().map(|(variant_name, struct_def)| {
         let pallet_name = &pallet.name;
@@ -77,9 +79,12 @@ 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();
+    let docs = should_gen_docs
+        .then_some(quote! { #( #[doc = #docs ] )* })
+        .unwrap_or_default();
 
     quote! {
-        #( #[doc = #docs ] )*
+        #docs
         pub type Event = #event_type;
         pub mod events {
             use super::#types_mod_ident;

codegen/src/api/mod.rs

@@ -56,6 +56,7 @@ use syn::parse_quote;
 /// * `derives` - Provide custom derives for the generated types.
 /// * `type_substitutes` - Provide custom type substitutes.
 /// * `crate_path` - Path to the `subxt` crate.
+/// * `should_gen_docs` - True if the generated API contains the documentation from the metadata.
 ///
 /// **Note:** This is a wrapper over [RuntimeGenerator] for static metadata use-cases.
 pub fn generate_runtime_api_from_path<P>(
@@ -64,6 +65,7 @@ pub fn generate_runtime_api_from_path<P>(
     derives: DerivesRegistry,
     type_substitutes: TypeSubstitutes,
     crate_path: CratePath,
+    should_gen_docs: bool,
 ) -> TokenStream2
 where
     P: AsRef<path::Path>,
@@ -82,6 +84,7 @@ where
         derives,
         type_substitutes,
         crate_path,
+        should_gen_docs,
     )
 }
 
@@ -96,6 +99,7 @@ where
 /// * `derives` - Provide custom derives for the generated types.
 /// * `type_substitutes` - Provide custom type substitutes.
 /// * `crate_path` - Path to the `subxt` crate.
+/// * `should_gen_docs` - True if the generated API contains the documentation from the metadata.
 ///
 /// **Note:** This is a wrapper over [RuntimeGenerator] for static metadata use-cases.
 pub fn generate_runtime_api_from_url(
@@ -104,6 +108,7 @@ pub fn generate_runtime_api_from_url(
     derives: DerivesRegistry,
     type_substitutes: TypeSubstitutes,
     crate_path: CratePath,
+    should_gen_docs: bool,
 ) -> TokenStream2 {
     let bytes = fetch_metadata_bytes_blocking(url)
         .unwrap_or_else(|e| abort_call_site!("Failed to obtain metadata: {}", e));
@@ -114,6 +119,7 @@ pub fn generate_runtime_api_from_url(
         derives,
         type_substitutes,
         crate_path,
+        should_gen_docs,
     )
 }
 
@@ -126,6 +132,7 @@ pub fn generate_runtime_api_from_url(
 /// * `derives` - Provide custom derives for the generated types.
 /// * `type_substitutes` - Provide custom type substitutes.
 /// * `crate_path` - Path to the `subxt` crate.
+/// * `should_gen_docs` - True if the generated API contains the documentation from the metadata.
 ///
 /// **Note:** This is a wrapper over [RuntimeGenerator] for static metadata use-cases.
 pub fn generate_runtime_api_from_bytes(
@@ -134,12 +141,19 @@ pub fn generate_runtime_api_from_bytes(
     derives: DerivesRegistry,
     type_substitutes: TypeSubstitutes,
     crate_path: CratePath,
+    should_gen_docs: bool,
 ) -> TokenStream2 {
     let metadata = frame_metadata::RuntimeMetadataPrefixed::decode(&mut &bytes[..])
         .unwrap_or_else(|e| abort_call_site!("Failed to decode metadata: {}", e));
 
     let generator = RuntimeGenerator::new(metadata);
-    generator.generate_runtime(item_mod, derives, type_substitutes, crate_path)
+    generator.generate_runtime(
+        item_mod,
+        derives,
+        type_substitutes,
+        crate_path,
+        should_gen_docs,
+    )
 }
 
 /// Create the API for interacting with a Substrate runtime.
@@ -172,6 +186,7 @@ impl RuntimeGenerator {
         derives: DerivesRegistry,
         type_substitutes: TypeSubstitutes,
         crate_path: CratePath,
+        should_gen_docs: bool,
     ) -> TokenStream2 {
         let item_mod_attrs = item_mod.attrs.clone();
         let item_mod_ir = ir::ItemMod::from(item_mod);
@@ -183,6 +198,7 @@ impl RuntimeGenerator {
             type_substitutes,
             derives.clone(),
             crate_path.clone(),
+            should_gen_docs,
         );
         let types_mod = type_gen.generate_types_mod();
         let types_mod_ident = types_mod.ident();
@@ -218,10 +234,16 @@ impl RuntimeGenerator {
                 pallet,
                 types_mod_ident,
                 &crate_path,
+                should_gen_docs,
             );
 
-            let event =
-                events::generate_events(&type_gen, pallet, types_mod_ident, &crate_path);
+            let event = events::generate_events(
+                &type_gen,
+                pallet,
+                types_mod_ident,
+                &crate_path,
+                should_gen_docs,
+            );
 
             let storage_mod = storage::generate_storage(
                 &self.metadata,
@@ -229,6 +251,7 @@ impl RuntimeGenerator {
                 pallet,
                 types_mod_ident,
                 &crate_path,
+                should_gen_docs,
             );
 
             let constants_mod = constants::generate_constants(
@@ -237,6 +260,7 @@ impl RuntimeGenerator {
                 pallet,
                 types_mod_ident,
                 &crate_path,
+                should_gen_docs,
             );
 
             quote! {
@@ -376,6 +400,7 @@ pub fn generate_structs_from_variants<F>(
     variant_to_struct_name: F,
     error_message_type_name: &str,
     crate_path: &CratePath,
+    should_gen_docs: bool,
 ) -> Vec<(String, CompositeDef)>
 where
     F: Fn(&str) -> std::borrow::Cow<str>,
@@ -393,6 +418,7 @@ where
                     &[],
                     type_gen,
                 );
+                let docs = should_gen_docs.then_some(var.docs()).unwrap_or_default();
                 let struct_def = CompositeDef::struct_def(
                     &ty,
                     struct_name.as_ref(),
@@ -400,7 +426,7 @@ where
                     fields,
                     Some(parse_quote!(pub)),
                     type_gen,
-                    var.docs(),
+                    docs,
                     crate_path,
                 );
                 (var.name().to_string(), struct_def)

codegen/src/api/storage.rs

@@ -41,6 +41,7 @@ pub fn generate_storage(
     pallet: &PalletMetadata<PortableForm>,
     types_mod_ident: &syn::Ident,
     crate_path: &CratePath,
+    should_gen_docs: bool,
 ) -> TokenStream2 {
     let storage = if let Some(ref storage) = pallet.storage {
         storage
@@ -52,7 +53,14 @@ pub fn generate_storage(
         .entries
         .iter()
         .map(|entry| {
-            generate_storage_entry_fns(metadata, type_gen, pallet, entry, crate_path)
+            generate_storage_entry_fns(
+                metadata,
+                type_gen,
+                pallet,
+                entry,
+                crate_path,
+                should_gen_docs,
+            )
         })
         .collect();
 
@@ -75,6 +83,7 @@ fn generate_storage_entry_fns(
     pallet: &PalletMetadata<PortableForm>,
     storage_entry: &StorageEntryMetadata<PortableForm>,
     crate_path: &CratePath,
+    should_gen_docs: bool,
 ) -> TokenStream2 {
     let (fields, key_impl) = match storage_entry.ty {
         StorageEntryType::Plain(_) => (vec![], quote!(vec![])),
@@ -183,7 +192,9 @@ fn generate_storage_entry_fns(
     let storage_entry_value_ty = type_gen.resolve_type_path(storage_entry_ty.id());
 
     let docs = &storage_entry.docs;
-    let docs_token = quote! { #( #[doc = #docs ] )* };
+    let docs = should_gen_docs
+        .then_some(quote! { #( #[doc = #docs ] )* })
+        .unwrap_or_default();
 
     let key_args = fields.iter().map(|(field_name, field_type)| {
         // The field type is translated from `std::vec::Vec<T>` to `[T]`. We apply
@@ -224,7 +235,7 @@ fn generate_storage_entry_fns(
     let root_entry_fn = if is_map_type {
         let fn_name_root = format_ident!("{}_root", fn_name);
         quote! (
-            #docs_token
+            #docs
             pub fn #fn_name_root(
                 &self,
             ) -> #crate_path::storage::address::StaticStorageAddress::<#crate_path::metadata::DecodeStaticType<#storage_entry_value_ty>, (), #is_defaultable_type, #is_iterable_type> {
@@ -242,7 +253,7 @@ fn generate_storage_entry_fns(
 
     quote! {
         // Access a specific value from a storage entry
-        #docs_token
+        #docs
         pub fn #fn_name(
             &self,
             #( #key_args, )*

codegen/src/lib.rs

@@ -37,7 +37,9 @@
 //! let substs = TypeSubstitutes::new(&CratePath::default());
 //! // Generate the Runtime API.
 //! let generator = subxt_codegen::RuntimeGenerator::new(metadata);
-//! let runtime_api = generator.generate_runtime(item_mod, derives, substs, CratePath::default());
+//! // Include metadata documentation in the Runtime API.
+//! let generate_docs = true;
+//! let runtime_api = generator.generate_runtime(item_mod, derives, substs, CratePath::default(), generate_docs);
 //! println!("{}", runtime_api);
 //! ```
 

codegen/src/types/mod.rs

@@ -65,6 +65,8 @@ pub struct TypeGenerator<'a> {
     derives: DerivesRegistry,
     /// The `subxt` crate access path in the generated code.
     crate_path: CratePath,
+    /// True if codegen should generate the documentation for the API.
+    should_gen_docs: bool,
 }
 
 impl<'a> TypeGenerator<'a> {
@@ -75,6 +77,7 @@ impl<'a> TypeGenerator<'a> {
         type_substitutes: TypeSubstitutes,
         derives: DerivesRegistry,
         crate_path: CratePath,
+        should_gen_docs: bool,
     ) -> Self {
         let root_mod_ident = Ident::new(root_mod, Span::call_site());
         Self {
@@ -83,6 +86,7 @@ impl<'a> TypeGenerator<'a> {
             type_substitutes,
             derives,
             crate_path,
+            should_gen_docs,
         }
     }
 
@@ -118,7 +122,12 @@ impl<'a> TypeGenerator<'a> {
 
             innermost_module.types.insert(
                 path.clone(),
-                TypeDefGen::from_type(ty.ty(), self, &self.crate_path),
+                TypeDefGen::from_type(
+                    ty.ty(),
+                    self,
+                    &self.crate_path,
+                    self.should_gen_docs,
+                ),
             );
         }
 

codegen/src/types/tests.rs

@@ -46,6 +46,7 @@ fn generate_struct_with_primitives() {
         TypeSubstitutes::new(&crate_path),
         DerivesRegistry::new(&crate_path),
         crate_path,
+        true,
     );
     let types = type_gen.generate_types_mod();
     let tests_mod = get_mod(&types, MOD_PATH).unwrap();
@@ -94,6 +95,7 @@ fn generate_struct_with_a_struct_field() {
         TypeSubstitutes::new(&crate_path),
         DerivesRegistry::new(&crate_path),
         crate_path,
+        true,
     );
     let types = type_gen.generate_types_mod();
     let tests_mod = get_mod(&types, MOD_PATH).unwrap();
@@ -141,6 +143,7 @@ fn generate_tuple_struct() {
         TypeSubstitutes::new(&crate_path),
         DerivesRegistry::new(&crate_path),
         crate_path,
+        true,
     );
     let types = type_gen.generate_types_mod();
     let tests_mod = get_mod(&types, MOD_PATH).unwrap();
@@ -225,6 +228,7 @@ fn derive_compact_as_for_uint_wrapper_structs() {
         TypeSubstitutes::new(&crate_path),
         DerivesRegistry::new(&crate_path),
         crate_path,
+        true,
     );
     let types = type_gen.generate_types_mod();
     let tests_mod = get_mod(&types, MOD_PATH).unwrap();
@@ -291,6 +295,7 @@ fn generate_enum() {
         TypeSubstitutes::new(&crate_path),
         DerivesRegistry::new(&crate_path),
         crate_path,
+        true,
     );
     let types = type_gen.generate_types_mod();
     let tests_mod = get_mod(&types, MOD_PATH).unwrap();
@@ -351,6 +356,7 @@ fn compact_fields() {
         TypeSubstitutes::new(&crate_path),
         DerivesRegistry::new(&crate_path),
         crate_path,
+        true,
     );
     let types = type_gen.generate_types_mod();
     let tests_mod = get_mod(&types, MOD_PATH).unwrap();
@@ -409,6 +415,7 @@ fn compact_generic_parameter() {
         TypeSubstitutes::new(&crate_path),
         DerivesRegistry::new(&crate_path),
         crate_path,
+        true,
     );
     let types = type_gen.generate_types_mod();
     let tests_mod = get_mod(&types, MOD_PATH).unwrap();
@@ -452,6 +459,7 @@ fn generate_array_field() {
         TypeSubstitutes::new(&crate_path),
         DerivesRegistry::new(&crate_path),
         crate_path,
+        true,
     );
     let types = type_gen.generate_types_mod();
     let tests_mod = get_mod(&types, MOD_PATH).unwrap();
@@ -491,6 +499,7 @@ fn option_fields() {
         TypeSubstitutes::new(&crate_path),
         DerivesRegistry::new(&crate_path),
         crate_path,
+        true,
     );
     let types = type_gen.generate_types_mod();
     let tests_mod = get_mod(&types, MOD_PATH).unwrap();
@@ -533,6 +542,7 @@ fn box_fields_struct() {
         TypeSubstitutes::new(&crate_path),
         DerivesRegistry::new(&crate_path),
         crate_path,
+        true,
     );
     let types = type_gen.generate_types_mod();
     let tests_mod = get_mod(&types, MOD_PATH).unwrap();
@@ -575,6 +585,7 @@ fn box_fields_enum() {
         TypeSubstitutes::new(&crate_path),
         DerivesRegistry::new(&crate_path),
         crate_path,
+        true,
     );
     let types = type_gen.generate_types_mod();
     let tests_mod = get_mod(&types, MOD_PATH).unwrap();
@@ -617,6 +628,7 @@ fn range_fields() {
         TypeSubstitutes::new(&crate_path),
         DerivesRegistry::new(&crate_path),
         crate_path,
+        true,
     );
     let types = type_gen.generate_types_mod();
     let tests_mod = get_mod(&types, MOD_PATH).unwrap();
@@ -663,6 +675,7 @@ fn generics() {
         TypeSubstitutes::new(&crate_path),
         DerivesRegistry::new(&crate_path),
         crate_path,
+        true,
     );
     let types = type_gen.generate_types_mod();
     let tests_mod = get_mod(&types, MOD_PATH).unwrap();
@@ -713,6 +726,7 @@ fn generics_nested() {
         TypeSubstitutes::new(&crate_path),
         DerivesRegistry::new(&crate_path),
         crate_path,
+        true,
     );
     let types = type_gen.generate_types_mod();
     let tests_mod = get_mod(&types, MOD_PATH).unwrap();
@@ -766,6 +780,7 @@ fn generate_bitvec() {
         TypeSubstitutes::new(&crate_path),
         DerivesRegistry::new(&crate_path),
         crate_path,
+        true,
     );
     let types = type_gen.generate_types_mod();
     let tests_mod = get_mod(&types, MOD_PATH).unwrap();
@@ -821,6 +836,7 @@ fn generics_with_alias_adds_phantom_data_marker() {
         TypeSubstitutes::new(&crate_path),
         DerivesRegistry::new(&crate_path),
         crate_path,
+        true,
     );
     let types = type_gen.generate_types_mod();
     let tests_mod = get_mod(&types, MOD_PATH).unwrap();
@@ -883,6 +899,7 @@ fn modules() {
         TypeSubstitutes::new(&crate_path),
         DerivesRegistry::new(&crate_path),
         crate_path,
+        true,
     );
     let types = type_gen.generate_types_mod();
     let tests_mod = get_mod(&types, MOD_PATH).unwrap();
@@ -942,6 +959,7 @@ fn dont_force_struct_names_camel_case() {
         TypeSubstitutes::new(&crate_path),
         DerivesRegistry::new(&crate_path),
         crate_path,
+        true,
     );
     let types = type_gen.generate_types_mod();
     let tests_mod = get_mod(&types, MOD_PATH).unwrap();
@@ -985,6 +1003,7 @@ fn apply_user_defined_derives_for_all_types() {
         TypeSubstitutes::new(&crate_path),
         derives,
         crate_path,
+        true,
     );
     let types = type_gen.generate_types_mod();
     let tests_mod = get_mod(&types, MOD_PATH).unwrap();
@@ -1052,6 +1071,7 @@ fn apply_user_defined_derives_for_specific_types() {
         TypeSubstitutes::new(&crate_path),
         derives,
         crate_path,
+        true,
     );
     let types = type_gen.generate_types_mod();
     let tests_mod = get_mod(&types, MOD_PATH).unwrap();

codegen/src/types/type_def.rs

@@ -45,6 +45,7 @@ impl TypeDefGen {
         ty: &Type<PortableForm>,
         type_gen: &TypeGenerator,
         crate_path: &CratePath,
+        should_gen_docs: bool,
     ) -> Self {
         let derives = type_gen.type_derives(ty);
 
@@ -79,6 +80,7 @@ impl TypeDefGen {
                     type_gen,
                 );
                 type_params.update_unused(fields.field_types());
+                let docs = should_gen_docs.then_some(ty.docs()).unwrap_or_default();
                 let composite_def = CompositeDef::struct_def(
                     ty,
                     &type_name,
@@ -86,7 +88,7 @@ impl TypeDefGen {
                     fields,
                     Some(parse_quote!(pub)),
                     type_gen,
-                    ty.docs(),
+                    docs,
                     crate_path,
                 );
                 TypeDefGenKind::Struct(composite_def)
@@ -104,8 +106,10 @@ impl TypeDefGen {
                             type_gen,
                         );
                         type_params.update_unused(fields.field_types());
+                        let docs =
+                            should_gen_docs.then_some(v.docs()).unwrap_or_default();
                         let variant_def =
-                            CompositeDef::enum_variant_def(v.name(), fields, v.docs());
+                            CompositeDef::enum_variant_def(v.name(), fields, docs);
                         (v.index(), variant_def)
                     })
                     .collect();
@@ -116,7 +120,9 @@ impl TypeDefGen {
         };
 
         let docs = ty.docs();
-        let ty_docs = quote! { #( #[doc = #docs ] )* };
+        let ty_docs = should_gen_docs
+            .then_some(quote! { #( #[doc = #docs ] )* })
+            .unwrap_or_default();
 
         Self {
             type_params,