From ac69385af9578d7163e34a611862ce6b266e5524 Mon Sep 17 00:00:00 2001 From: Andrew Jones Date: Wed, 23 Jun 2021 11:06:46 +0100 Subject: [PATCH 1/4] WIP add docs feature --- Cargo.toml | 4 ++++ derive/Cargo.toml | 5 +++++ derive/src/lib.rs | 31 +++++++++++++++++++++++-------- 3 files changed, 32 insertions(+), 8 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index b701e96f..50e85cdd 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -30,6 +30,10 @@ std = [ derive = [ "scale-info-derive" ] +# Include code docs in type metadata. +docs = [ + "scale-info-derive/docs" +] # enables decoding and deserialization of portable scale-info type metadata decode = [ "scale/full" diff --git a/derive/Cargo.toml b/derive/Cargo.toml index dfaaa3e6..14e7e696 100644 --- a/derive/Cargo.toml +++ b/derive/Cargo.toml @@ -19,3 +19,8 @@ quote = "1.0" syn = { version = "1.0", features = ["derive", "visit", "visit-mut", "extra-traits"] } proc-macro2 = "1.0" proc-macro-crate = "1" + +[features] +default = [] +# Include code docs in type metadata. +docs = [] diff --git a/derive/src/lib.rs b/derive/src/lib.rs index 2653a0cf..baf5bd9b 100644 --- a/derive/src/lib.rs +++ b/derive/src/lib.rs @@ -104,7 +104,7 @@ fn generate_type(input: TokenStream2) -> Result { Data::Enum(ref e) => generate_variant_type(e, &scale_info), Data::Union(_) => return Err(Error::new_spanned(input, "Unions not supported")), }; - let docs = utils::get_doc_literals(&ast.attrs); + let docs = generate_docs(&ast.attrs); let type_info_impl = quote! { impl #impl_generics :: #scale_info ::TypeInfo for #ident #ty_generics #where_clause { @@ -113,7 +113,7 @@ fn generate_type(input: TokenStream2) -> Result { :: #scale_info ::Type::builder() .path(:: #scale_info ::Path::new(::core::stringify!(#ident), ::core::module_path!())) .type_params(:: #scale_info ::prelude::vec![ #( #generic_type_ids ),* ]) - .docs(&[ #( #docs ),* ]) + #docs .#build_type } } @@ -160,7 +160,7 @@ fn generate_fields(fields: &FieldsList) -> Vec { StaticLifetimesReplace.visit_type_mut(&mut ty); let type_name = clean_type_string("e!(#ty).to_string()); - let docs = utils::get_doc_literals(&f.attrs); + let docs = generate_docs(&f.attrs); let type_of_method = if utils::is_compact(f) { quote!(compact) } else { @@ -176,7 +176,7 @@ fn generate_fields(fields: &FieldsList) -> Vec { .#type_of_method::<#ty>() #name .type_name(#type_name) - .docs(&[ #( #docs ),* ]) + #docs ) ) }) @@ -235,12 +235,12 @@ fn generate_c_like_enum_def(variants: &VariantList, scale_info: &Ident) -> Token .map(|(i, v)| { let name = &v.ident; let discriminant = utils::variant_index(v, i); - let docs = utils::get_doc_literals(&v.attrs); + let docs = generate_docs(&v.attrs); quote! { .variant(::core::stringify!(#name), |v| v .discriminant(#discriminant as ::core::primitive::u64) - .docs(&[ #( #docs ),* ]) + #docs ) } }); @@ -272,7 +272,7 @@ fn generate_variant_type(data_enum: &DataEnum, scale_info: &Ident) -> TokenStrea .map(|v| { let ident = &v.ident; let v_name = quote! {::core::stringify!(#ident) }; - let docs = utils::get_doc_literals(&v.attrs); + let docs = generate_docs(&v.attrs); let index = utils::maybe_index(v).map(|i| quote!(.index(#i))); let fields = match v.fields { @@ -301,7 +301,7 @@ fn generate_variant_type(data_enum: &DataEnum, scale_info: &Ident) -> TokenStrea .variant(#v_name, |v| v .fields(#fields) - .docs(&[ #( #docs ),* ]) + #docs #index ) } @@ -313,3 +313,18 @@ fn generate_variant_type(data_enum: &DataEnum, scale_info: &Ident) -> TokenStrea ) } } + +// #[cfg(feature = "docs")] +#[cfg(not(feature = "docs"))] +fn generate_docs(attrs: &[syn::Attribute]) -> Option { + let docs = utils::get_doc_literals(attrs); + Some(quote! { + .docs(&[ #( #docs ),* ]) + }) +} + +// #[cfg(not(feature = "docs"))] +#[cfg(feature = "docs")] +fn generate_docs(_: &[syn::Attribute]) -> Option { + None +} From 54cc164f15e40b6ff629318525e143cc51b69fcf Mon Sep 17 00:00:00 2001 From: Andrew Jones Date: Wed, 23 Jun 2021 15:55:21 +0100 Subject: [PATCH 2/4] Add `docs` feature --- derive/src/lib.rs | 27 ++++++++++++++++++++++----- derive/src/utils.rs | 27 --------------------------- 2 files changed, 22 insertions(+), 32 deletions(-) diff --git a/derive/src/lib.rs b/derive/src/lib.rs index baf5bd9b..af46507b 100644 --- a/derive/src/lib.rs +++ b/derive/src/lib.rs @@ -314,17 +314,34 @@ fn generate_variant_type(data_enum: &DataEnum, scale_info: &Ident) -> TokenStrea } } -// #[cfg(feature = "docs")] -#[cfg(not(feature = "docs"))] +#[cfg(feature = "docs")] fn generate_docs(attrs: &[syn::Attribute]) -> Option { - let docs = utils::get_doc_literals(attrs); + let docs = attrs + .iter() + .filter_map(|attr| { + if let Ok(syn::Meta::NameValue(meta)) = attr.parse_meta() { + if meta.path.get_ident().map_or(false, |ident| ident == "doc") { + let lit = &meta.lit; + let doc_lit = quote!(#lit).to_string(); + let trimmed_doc_lit = + doc_lit.trim_start_matches(r#"" "#).trim_end_matches('"'); + let lit: syn::Lit = parse_quote!(#trimmed_doc_lit); + Some(lit) + } else { + None + } + } else { + None + } + }) + .collect::>(); + Some(quote! { .docs(&[ #( #docs ),* ]) }) } -// #[cfg(not(feature = "docs"))] -#[cfg(feature = "docs")] +#[cfg(not(feature = "docs"))] fn generate_docs(_: &[syn::Attribute]) -> Option { None } diff --git a/derive/src/utils.rs b/derive/src/utils.rs index 5b54447c..2c6ea551 100644 --- a/derive/src/utils.rs +++ b/derive/src/utils.rs @@ -16,15 +16,10 @@ //! //! NOTE: The code here is copied verbatim from `parity-scale-codec-derive`. -use alloc::{ - string::ToString, - vec::Vec, -}; use proc_macro2::TokenStream; use quote::quote; use syn::{ parse::Parse, - parse_quote, punctuated::Punctuated, spanned::Spanned, token, @@ -37,28 +32,6 @@ use syn::{ Variant, }; -/// Return all doc attributes literals found. -pub fn get_doc_literals(attrs: &[syn::Attribute]) -> Vec { - attrs - .iter() - .filter_map(|attr| { - if let Ok(syn::Meta::NameValue(meta)) = attr.parse_meta() { - if meta.path.get_ident().map_or(false, |ident| ident == "doc") { - let lit = &meta.lit; - let doc_lit = quote!(#lit).to_string(); - let trimmed_doc_lit = - doc_lit.trim_start_matches(r#"" "#).trim_end_matches('"'); - Some(parse_quote!(#trimmed_doc_lit)) - } else { - None - } - } else { - None - } - }) - .collect() -} - /// Trait bounds. pub type TraitBounds = Punctuated; From 1e644227ad68b55e7ac697af5bb1fb711fa30b1f Mon Sep 17 00:00:00 2001 From: Andrew Jones Date: Wed, 23 Jun 2021 16:11:49 +0100 Subject: [PATCH 3/4] Make `docs` a default feature --- .github/workflows/rust.yml | 1 + Cargo.toml | 2 +- derive/Cargo.toml | 2 +- 3 files changed, 3 insertions(+), 2 deletions(-) diff --git a/.github/workflows/rust.yml b/.github/workflows/rust.yml index e3aabf2d..d88de063 100644 --- a/.github/workflows/rust.yml +++ b/.github/workflows/rust.yml @@ -40,6 +40,7 @@ jobs: - name: check-features run: | cargo check --no-default-features --features bit-vec + cargo check --no-default-features --features docs cargo check --no-default-features --features serde cargo check --no-default-features --features serde,decode diff --git a/Cargo.toml b/Cargo.toml index 50e85cdd..82a3300a 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -22,7 +22,7 @@ derive_more = { version = "0.99.1", default-features = false, features = ["from" scale = { package = "parity-scale-codec", version = "2.1", default-features = false, features = ["derive"] } [features] -default = ["std"] +default = ["std", "docs"] std = [ "bitvec/std", "scale/std", diff --git a/derive/Cargo.toml b/derive/Cargo.toml index 14e7e696..aa2db68f 100644 --- a/derive/Cargo.toml +++ b/derive/Cargo.toml @@ -21,6 +21,6 @@ proc-macro2 = "1.0" proc-macro-crate = "1" [features] -default = [] +default = ["docs"] # Include code docs in type metadata. docs = [] From 859f74ae4f76d41791ec20073bcc6a35619e66de Mon Sep 17 00:00:00 2001 From: Andrew Jones Date: Wed, 23 Jun 2021 16:12:14 +0100 Subject: [PATCH 4/4] Update Cargo.toml Co-authored-by: David --- Cargo.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Cargo.toml b/Cargo.toml index 82a3300a..50fd2432 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -30,7 +30,7 @@ std = [ derive = [ "scale-info-derive" ] -# Include code docs in type metadata. +# Include rustdoc strings in the type metadata. docs = [ "scale-info-derive/docs" ]