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/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,