From f7aee84c1ff778a9c19354203c6cb5dd71f9db33 Mon Sep 17 00:00:00 2001 From: Julian Frimmel Date: Sun, 15 Dec 2019 16:24:48 +0100 Subject: [PATCH 1/6] Prodvide a cfg for the doc-cfg feature To be able to include banners, which feature is needed for an item, the feature `#![feature(doc_cfg)]` has to be available. This feture is only available in nightly compiler since August 2017. So we need to detect, whether we are building the docs under a nightly compiler to add the doc-cfg-banners. --- build.rs | 2 ++ 1 file changed, 2 insertions(+) diff --git a/build.rs b/build.rs index c0f9ed3406..c97ff5400a 100644 --- a/build.rs +++ b/build.rs @@ -17,6 +17,8 @@ fn main() { if !compiler.nightly { println!("cargo:rustc-cfg=syn_disable_nightly_tests"); + } else { + println!("cargo:rustc-cfg=syn_enable_doc_cfg"); } } From a52366939284d289febdfe0b089a45877d663957 Mon Sep 17 00:00:00 2001 From: Julian Frimmel Date: Sun, 15 Dec 2019 16:26:58 +0100 Subject: [PATCH 2/6] Enable `doc_cfg` feature conditionally This enables the usage of the #[doc(cfg(...))] attributes. --- src/lib.rs | 1 + 1 file changed, 1 insertion(+) diff --git a/src/lib.rs b/src/lib.rs index 50abe8168b..35a085cb4b 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -244,6 +244,7 @@ // Syn types in rustdoc of other crates get linked to here. #![doc(html_root_url = "https://docs.rs/syn/1.0.11")] #![deny(clippy::all, clippy::pedantic)] +#![cfg_attr(syn_enable_doc_cfg, feature(doc_cfg))] // Ignored clippy lints. #![allow( clippy::block_in_if_condition_stmt, From 078af2bcd098fa9c8b0ee1c44fe9262a8d792565 Mon Sep 17 00:00:00 2001 From: Julian Frimmel Date: Mon, 16 Dec 2019 19:40:18 +0100 Subject: [PATCH 3/6] Apply `#[doc(cfg(..))]` attributes to public types --- src/attr.rs | 28 +++++++++++++++++ src/data.rs | 36 +++++++++++++++++++++ src/derive.rs | 5 +++ src/expr.rs | 78 ++++++++++++++++++++++++++++++++++++++++++++++ src/file.rs | 1 + src/generics.rs | 68 ++++++++++++++++++++++++++++++++++++++++ src/item.rs | 41 ++++++++++++++++++++++++ src/lib.rs | 10 ++++++ src/lit.rs | 36 +++++++++++++++++++++ src/mac.rs | 8 +++++ src/op.rs | 8 +++++ src/parse_quote.rs | 1 + src/pat.rs | 17 ++++++++++ src/path.rs | 36 +++++++++++++++++++++ src/stmt.rs | 3 ++ src/ty.rs | 76 ++++++++++++++++++++++++++++++++++++++++++++ 16 files changed, 452 insertions(+) diff --git a/src/attr.rs b/src/attr.rs index a8e16ea602..d4cc3e23af 100644 --- a/src/attr.rs +++ b/src/attr.rs @@ -148,6 +148,10 @@ ast_struct! { /// }; /// assert_eq!(doc, attr); /// ``` + #[cfg_attr( + syn_enable_doc_cfg, + doc(cfg(any(feature = "derive", feature = "full"))) + )] pub struct Attribute #manual_extra_traits { pub pound_token: Token![#], pub style: AttrStyle, @@ -349,6 +353,10 @@ ast_enum! { /// - `#![feature(proc_macro)]` /// - `//! # Example` /// - `/*! Please file an issue */` + #[cfg_attr( + syn_enable_doc_cfg, + doc(cfg(any(feature = "derive", feature = "full"))) + )] #[cfg_attr(feature = "clone-impls", derive(Copy))] pub enum AttrStyle { Outer, @@ -383,6 +391,10 @@ ast_enum_of_structs! { // // TODO: change syntax-tree-enum link to an intra rustdoc link, currently // blocked on https://github.com/rust-lang/rust/issues/62833 + #[cfg_attr( + syn_enable_doc_cfg, + doc(cfg(any(feature = "derive", feature = "full"))) + )] pub enum Meta { Path(Path), @@ -399,6 +411,10 @@ ast_struct! { /// /// *This type is available if Syn is built with the `"derive"` or /// `"full"` feature.* + #[cfg_attr( + syn_enable_doc_cfg, + doc(cfg(any(feature = "derive", feature = "full"))) + )] pub struct MetaList { pub path: Path, pub paren_token: token::Paren, @@ -411,6 +427,10 @@ ast_struct! { /// /// *This type is available if Syn is built with the `"derive"` or /// `"full"` feature.* + #[cfg_attr( + syn_enable_doc_cfg, + doc(cfg(any(feature = "derive", feature = "full"))) + )] pub struct MetaNameValue { pub path: Path, pub eq_token: Token![=], @@ -437,6 +457,10 @@ ast_enum_of_structs! { /// /// *This type is available if Syn is built with the `"derive"` or `"full"` /// feature.* + #[cfg_attr( + syn_enable_doc_cfg, + doc(cfg(any(feature = "derive", feature = "full"))) + )] pub enum NestedMeta { /// A structured meta item, like the `Copy` in `#[derive(Copy)]` which /// would be a nested `Meta::Path`. @@ -482,6 +506,10 @@ ast_enum_of_structs! { /// # "".parse().unwrap() /// } /// ``` +#[cfg_attr( + syn_enable_doc_cfg, + doc(cfg(any(feature = "derive", feature = "full"))) +)] pub type AttributeArgs = Vec; pub trait FilterAttrs<'a> { diff --git a/src/data.rs b/src/data.rs index 184a79eb52..c8e99657d1 100644 --- a/src/data.rs +++ b/src/data.rs @@ -6,6 +6,10 @@ ast_struct! { /// /// *This type is available if Syn is built with the `"derive"` or `"full"` /// feature.* + #[cfg_attr( + syn_enable_doc_cfg, + doc(cfg(any(feature = "derive", feature = "full"))) + )] pub struct Variant { /// Attributes tagged on the variant. pub attrs: Vec, @@ -35,6 +39,10 @@ ast_enum_of_structs! { // // TODO: change syntax-tree-enum link to an intra rustdoc link, currently // blocked on https://github.com/rust-lang/rust/issues/62833 + #[cfg_attr( + syn_enable_doc_cfg, + doc(cfg(any(feature = "derive", feature = "full"))) + )] pub enum Fields { /// Named fields of a struct or struct variant such as `Point { x: f64, /// y: f64 }`. @@ -54,6 +62,10 @@ ast_struct! { /// /// *This type is available if Syn is built with the `"derive"` or /// `"full"` feature.* + #[cfg_attr( + syn_enable_doc_cfg, + doc(cfg(any(feature = "derive", feature = "full"))) + )] pub struct FieldsNamed { pub brace_token: token::Brace, pub named: Punctuated, @@ -65,6 +77,10 @@ ast_struct! { /// /// *This type is available if Syn is built with the `"derive"` or /// `"full"` feature.* + #[cfg_attr( + syn_enable_doc_cfg, + doc(cfg(any(feature = "derive", feature = "full"))) + )] pub struct FieldsUnnamed { pub paren_token: token::Paren, pub unnamed: Punctuated, @@ -149,6 +165,10 @@ ast_struct! { /// /// *This type is available if Syn is built with the `"derive"` or `"full"` /// feature.* + #[cfg_attr( + syn_enable_doc_cfg, + doc(cfg(any(feature = "derive", feature = "full"))) + )] pub struct Field { /// Attributes tagged on the field. pub attrs: Vec, @@ -183,6 +203,10 @@ ast_enum_of_structs! { // // TODO: change syntax-tree-enum link to an intra rustdoc link, currently // blocked on https://github.com/rust-lang/rust/issues/62833 + #[cfg_attr( + syn_enable_doc_cfg, + doc(cfg(any(feature = "derive", feature = "full"))) + )] pub enum Visibility { /// A public visibility level: `pub`. Public(VisPublic), @@ -204,6 +228,10 @@ ast_struct! { /// /// *This type is available if Syn is built with the `"derive"` or /// `"full"` feature.* + #[cfg_attr( + syn_enable_doc_cfg, + doc(cfg(any(feature = "derive", feature = "full"))) + )] pub struct VisPublic { pub pub_token: Token![pub], } @@ -214,6 +242,10 @@ ast_struct! { /// /// *This type is available if Syn is built with the `"derive"` or /// `"full"` feature.* + #[cfg_attr( + syn_enable_doc_cfg, + doc(cfg(any(feature = "derive", feature = "full"))) + )] pub struct VisCrate { pub crate_token: Token![crate], } @@ -225,6 +257,10 @@ ast_struct! { /// /// *This type is available if Syn is built with the `"derive"` or /// `"full"` feature.* + #[cfg_attr( + syn_enable_doc_cfg, + doc(cfg(any(feature = "derive", feature = "full"))) + )] pub struct VisRestricted { pub pub_token: Token![pub], pub paren_token: token::Paren, diff --git a/src/derive.rs b/src/derive.rs index 8cb9cf7b6d..45ed90b81d 100644 --- a/src/derive.rs +++ b/src/derive.rs @@ -5,6 +5,7 @@ ast_struct! { /// Data structure sent to a `proc_macro_derive` macro. /// /// *This type is available if Syn is built with the `"derive"` feature.* + #[cfg_attr(syn_enable_doc_cfg, doc(cfg(feature = "derive")))] pub struct DeriveInput { /// Attributes tagged on the whole struct or enum. pub attrs: Vec, @@ -36,6 +37,7 @@ ast_enum_of_structs! { // // TODO: change syntax-tree-enum link to an intra rustdoc link, currently // blocked on https://github.com/rust-lang/rust/issues/62833 + #[cfg_attr(syn_enable_doc_cfg, doc(cfg(feature = "derive")))] pub enum Data { /// A struct input to a `proc_macro_derive` macro. Struct(DataStruct), @@ -55,6 +57,7 @@ ast_struct! { /// /// *This type is available if Syn is built with the `"derive"` /// feature.* + #[cfg_attr(syn_enable_doc_cfg, doc(cfg(feature = "derive")))] pub struct DataStruct { pub struct_token: Token![struct], pub fields: Fields, @@ -67,6 +70,7 @@ ast_struct! { /// /// *This type is available if Syn is built with the `"derive"` /// feature.* + #[cfg_attr(syn_enable_doc_cfg, doc(cfg(feature = "derive")))] pub struct DataEnum { pub enum_token: Token![enum], pub brace_token: token::Brace, @@ -79,6 +83,7 @@ ast_struct! { /// /// *This type is available if Syn is built with the `"derive"` /// feature.* + #[cfg_attr(syn_enable_doc_cfg, doc(cfg(feature = "derive")))] pub struct DataUnion { pub union_token: Token![union], pub fields: FieldsNamed, diff --git a/src/expr.rs b/src/expr.rs index 603dc32e13..e246eee5be 100644 --- a/src/expr.rs +++ b/src/expr.rs @@ -86,6 +86,10 @@ ast_enum_of_structs! { /// A sign that you may not be choosing the right variable names is if you /// see names getting repeated in your code, like accessing /// `receiver.receiver` or `pat.pat` or `cond.cond`. + #[cfg_attr( + syn_enable_doc_cfg, + doc(cfg(any(feature = "derive", feature = "full"))) + )] pub enum Expr #manual_extra_traits { /// A slice literal expression: `[a, b, c, d]`. Array(ExprArray), @@ -232,6 +236,7 @@ ast_struct! { /// A slice literal expression: `[a, b, c, d]`. /// /// *This type is available if Syn is built with the `"full"` feature.* + #[cfg_attr(syn_enable_doc_cfg, doc(cfg(feature = "full")))] pub struct ExprArray #full { pub attrs: Vec, pub bracket_token: token::Bracket, @@ -243,6 +248,7 @@ ast_struct! { /// An assignment expression: `a = compute()`. /// /// *This type is available if Syn is built with the `"full"` feature.* + #[cfg_attr(syn_enable_doc_cfg, doc(cfg(feature = "full")))] pub struct ExprAssign #full { pub attrs: Vec, pub left: Box, @@ -255,6 +261,7 @@ ast_struct! { /// A compound assignment expression: `counter += 1`. /// /// *This type is available if Syn is built with the `"full"` feature.* + #[cfg_attr(syn_enable_doc_cfg, doc(cfg(feature = "full")))] pub struct ExprAssignOp #full { pub attrs: Vec, pub left: Box, @@ -267,6 +274,7 @@ ast_struct! { /// An async block: `async { ... }`. /// /// *This type is available if Syn is built with the `"full"` feature.* + #[cfg_attr(syn_enable_doc_cfg, doc(cfg(feature = "full")))] pub struct ExprAsync #full { pub attrs: Vec, pub async_token: Token![async], @@ -279,6 +287,7 @@ ast_struct! { /// An await expression: `fut.await`. /// /// *This type is available if Syn is built with the `"full"` feature.* + #[cfg_attr(syn_enable_doc_cfg, doc(cfg(feature = "full")))] pub struct ExprAwait #full { pub attrs: Vec, pub base: Box, @@ -292,6 +301,10 @@ ast_struct! { /// /// *This type is available if Syn is built with the `"derive"` or /// `"full"` feature.* + #[cfg_attr( + syn_enable_doc_cfg, + doc(cfg(any(feature = "derive", feature = "full"))) + )] pub struct ExprBinary { pub attrs: Vec, pub left: Box, @@ -304,6 +317,7 @@ ast_struct! { /// A blocked scope: `{ ... }`. /// /// *This type is available if Syn is built with the `"full"` feature.* + #[cfg_attr(syn_enable_doc_cfg, doc(cfg(feature = "full")))] pub struct ExprBlock #full { pub attrs: Vec, pub label: Option