diff --git a/Cargo.toml b/Cargo.toml index 7a53a63bbc..0fbb45eda2 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -64,6 +64,7 @@ required-features = ["full", "parsing"] [package.metadata.docs.rs] all-features = true targets = ["x86_64-unknown-linux-gnu"] +rustdoc-args = ["--cfg", "docsrs"] [package.metadata.playground] features = ["full", "visit", "visit-mut", "fold", "extra-traits"] diff --git a/src/attr.rs b/src/attr.rs index 2a51c3801b..80d1c21a7d 100644 --- a/src/attr.rs +++ b/src/attr.rs @@ -17,11 +17,6 @@ use std::hash::{Hash, Hasher}; ast_struct! { /// An attribute like `#[repr(transparent)]`. /// - /// *This type is available only if Syn is built with the `"derive"` or `"full"` - /// feature.* - /// - ///
- /// /// # Syntax /// /// Rust has six types of attributes. @@ -148,6 +143,7 @@ ast_struct! { /// }; /// assert_eq!(doc, attr); /// ``` + #[cfg_attr(docsrs, doc(cfg(any(feature = "derive", feature = "full"))))] pub struct Attribute #manual_extra_traits { pub pound_token: Token![#], pub style: AttrStyle, @@ -188,10 +184,8 @@ impl Hash for Attribute { impl Attribute { /// Parses the content of the attribute, consisting of the path and tokens, /// as a [`Meta`] if possible. - /// - /// *This function is available only if Syn is built with the `"parsing"` - /// feature.* #[cfg(feature = "parsing")] + #[cfg_attr(docsrs, doc(cfg(feature = "parsing")))] pub fn parse_meta(&self) -> Result { fn clone_ident_segment(segment: &PathSegment) -> PathSegment { PathSegment { @@ -235,19 +229,15 @@ impl Attribute { /// #[my_attr(value < 5)] /// ^^^^^^^^^ what gets parsed /// ``` - /// - /// *This function is available only if Syn is built with the `"parsing"` - /// feature.* #[cfg(feature = "parsing")] + #[cfg_attr(docsrs, doc(cfg(feature = "parsing")))] pub fn parse_args(&self) -> Result { self.parse_args_with(T::parse) } /// Parse the arguments to the attribute using the given parser. - /// - /// *This function is available only if Syn is built with the `"parsing"` - /// feature.* #[cfg(feature = "parsing")] + #[cfg_attr(docsrs, doc(cfg(feature = "parsing")))] pub fn parse_args_with(&self, parser: F) -> Result { let parser = |input: ParseStream| { let args = enter_args(self, input)?; @@ -257,10 +247,8 @@ impl Attribute { } /// Parses zero or more outer attributes from the stream. - /// - /// *This function is available only if Syn is built with the `"parsing"` - /// feature.* #[cfg(feature = "parsing")] + #[cfg_attr(docsrs, doc(cfg(feature = "parsing")))] pub fn parse_outer(input: ParseStream) -> Result> { let mut attrs = Vec::new(); while input.peek(Token![#]) && !input.peek(token::Group) { @@ -270,10 +258,8 @@ impl Attribute { } /// Parses zero or more inner attributes from the stream. - /// - /// *This function is available only if Syn is built with the `"parsing"` - /// feature.* #[cfg(feature = "parsing")] + #[cfg_attr(docsrs, doc(cfg(feature = "parsing")))] pub fn parse_inner(input: ParseStream) -> Result> { let mut attrs = Vec::new(); while input.peek(Token![#]) && input.peek2(Token![!]) && !input.peek(token::Group) { @@ -339,9 +325,6 @@ ast_enum! { /// Distinguishes between attributes that decorate an item and attributes /// that are contained within an item. /// - /// *This type is available only if Syn is built with the `"derive"` or `"full"` - /// feature.* - /// /// # Outer attributes /// /// - `#[repr(transparent)]` @@ -354,6 +337,7 @@ ast_enum! { /// - `//! # Example` /// - `/*! Please file an issue */` #[cfg_attr(feature = "clone-impls", derive(Copy))] + #[cfg_attr(docsrs, doc(cfg(any(feature = "derive", feature = "full"))))] pub enum AttrStyle { Outer, Inner(Token![!]), @@ -363,9 +347,6 @@ ast_enum! { ast_enum_of_structs! { /// Content of a compile-time structured attribute. /// - /// *This type is available only if Syn is built with the `"derive"` or `"full"` - /// feature.* - /// /// ## Path /// /// A meta path is like the `test` in `#[test]`. @@ -387,6 +368,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(docsrs, doc(cfg(any(feature = "derive", feature = "full"))))] pub enum Meta { Path(Path), @@ -400,9 +382,7 @@ ast_enum_of_structs! { ast_struct! { /// A structured list within an attribute, like `derive(Copy, Clone)`. - /// - /// *This type is available only if Syn is built with the `"derive"` or - /// `"full"` feature.* + #[cfg_attr(docsrs, doc(cfg(any(feature = "derive", feature = "full"))))] pub struct MetaList { pub path: Path, pub paren_token: token::Paren, @@ -412,9 +392,7 @@ ast_struct! { ast_struct! { /// A name-value pair within an attribute, like `feature = "nightly"`. - /// - /// *This type is available only if Syn is built with the `"derive"` or - /// `"full"` feature.* + #[cfg_attr(docsrs, doc(cfg(any(feature = "derive", feature = "full"))))] pub struct MetaNameValue { pub path: Path, pub eq_token: Token![=], @@ -438,9 +416,7 @@ impl Meta { ast_enum_of_structs! { /// Element of a compile-time attribute list. - /// - /// *This type is available only if Syn is built with the `"derive"` or `"full"` - /// feature.* + #[cfg_attr(docsrs, 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`. diff --git a/src/buffer.rs b/src/buffer.rs index 73255d6e9e..0005781d19 100644 --- a/src/buffer.rs +++ b/src/buffer.rs @@ -1,7 +1,7 @@ //! A stably addressed token buffer supporting efficient traversal based on a //! cheaply copyable cursor. -//! -//! *This module is available only if Syn is built with the `"parsing"` feature.* + +#![cfg_attr(docsrs, doc(cfg(feature = "parsing")))] // This module is heavily commented as it contains most of the unsafe code in // Syn, and caution should be used when editing it. The public-facing interface @@ -35,8 +35,7 @@ enum Entry { /// A buffer that can be efficiently traversed multiple times, unlike /// `TokenStream` which requires a deep copy in order to traverse more than /// once. -/// -/// *This type is available only if Syn is built with the `"parsing"` feature.* +#[cfg_attr(docsrs, doc(cfg(feature = "parsing")))] pub struct TokenBuffer { // NOTE: Do not derive clone on this - there are raw pointers inside which // will be messed up. Moving the `TokenBuffer` itself is safe as the actual @@ -97,13 +96,11 @@ impl TokenBuffer { /// Creates a `TokenBuffer` containing all the tokens from the input /// `TokenStream`. - /// - /// *This method is available only if Syn is built with both the `"parsing"` and - /// `"proc-macro"` features.* #[cfg(all( not(all(target_arch = "wasm32", any(target_os = "unknown", target_os = "wasi"))), feature = "proc-macro" ))] + #[cfg_attr(docsrs, doc(cfg(all(feature = "parsing", feature = "proc-macro"))))] pub fn new(stream: pm::TokenStream) -> TokenBuffer { Self::new2(stream.into()) } @@ -132,9 +129,8 @@ impl TokenBuffer { /// /// Two cursors are equal if they have the same location in the same input /// stream, and have the same scope. -/// -/// *This type is available only if Syn is built with the `"parsing"` feature.* #[derive(Copy, Clone, Eq, PartialEq)] +#[cfg_attr(docsrs, doc(cfg(feature = "parsing")))] pub struct Cursor<'a> { // The current entry which the `Cursor` is pointing at. ptr: *const Entry, diff --git a/src/data.rs b/src/data.rs index b217b8ca6f..3030c819fd 100644 --- a/src/data.rs +++ b/src/data.rs @@ -3,9 +3,7 @@ use crate::punctuated::Punctuated; ast_struct! { /// An enum variant. - /// - /// *This type is available only if Syn is built with the `"derive"` or `"full"` - /// feature.* + #[cfg_attr(docsrs, doc(cfg(any(feature = "derive", feature = "full"))))] pub struct Variant { /// Attributes tagged on the variant. pub attrs: Vec, @@ -24,9 +22,6 @@ ast_struct! { ast_enum_of_structs! { /// Data stored within an enum variant or struct. /// - /// *This type is available only if Syn is built with the `"derive"` or `"full"` - /// feature.* - /// /// # Syntax tree enum /// /// This type is a [syntax tree enum]. @@ -35,6 +30,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(docsrs, 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 }`. @@ -51,9 +47,7 @@ ast_enum_of_structs! { ast_struct! { /// Named fields of a struct or struct variant such as `Point { x: f64, /// y: f64 }`. - /// - /// *This type is available only if Syn is built with the `"derive"` or - /// `"full"` feature.* + #[cfg_attr(docsrs, doc(cfg(any(feature = "derive", feature = "full"))))] pub struct FieldsNamed { pub brace_token: token::Brace, pub named: Punctuated, @@ -62,9 +56,7 @@ ast_struct! { ast_struct! { /// Unnamed fields of a tuple struct or tuple variant such as `Some(T)`. - /// - /// *This type is available only if Syn is built with the `"derive"` or - /// `"full"` feature.* + #[cfg_attr(docsrs, doc(cfg(any(feature = "derive", feature = "full"))))] pub struct FieldsUnnamed { pub paren_token: token::Paren, pub unnamed: Punctuated, @@ -146,9 +138,7 @@ impl<'a> IntoIterator for &'a mut Fields { ast_struct! { /// A field of a struct or enum variant. - /// - /// *This type is available only if Syn is built with the `"derive"` or `"full"` - /// feature.* + #[cfg_attr(docsrs, doc(cfg(any(feature = "derive", feature = "full"))))] pub struct Field { /// Attributes tagged on the field. pub attrs: Vec, @@ -172,9 +162,6 @@ ast_enum_of_structs! { /// The visibility level of an item: inherited or `pub` or /// `pub(restricted)`. /// - /// *This type is available only if Syn is built with the `"derive"` or `"full"` - /// feature.* - /// /// # Syntax tree enum /// /// This type is a [syntax tree enum]. @@ -183,6 +170,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(docsrs, doc(cfg(any(feature = "derive", feature = "full"))))] pub enum Visibility { /// A public visibility level: `pub`. Public(VisPublic), @@ -201,9 +189,7 @@ ast_enum_of_structs! { ast_struct! { /// A public visibility level: `pub`. - /// - /// *This type is available only if Syn is built with the `"derive"` or - /// `"full"` feature.* + #[cfg_attr(docsrs, doc(cfg(any(feature = "derive", feature = "full"))))] pub struct VisPublic { pub pub_token: Token![pub], } @@ -211,9 +197,7 @@ ast_struct! { ast_struct! { /// A crate-level visibility: `crate`. - /// - /// *This type is available only if Syn is built with the `"derive"` or - /// `"full"` feature.* + #[cfg_attr(docsrs, doc(cfg(any(feature = "derive", feature = "full"))))] pub struct VisCrate { pub crate_token: Token![crate], } @@ -222,9 +206,7 @@ ast_struct! { ast_struct! { /// A visibility level restricted to some path: `pub(self)` or /// `pub(super)` or `pub(crate)` or `pub(in some::module)`. - /// - /// *This type is available only if Syn is built with the `"derive"` or - /// `"full"` feature.* + #[cfg_attr(docsrs, 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 3fa9d89a93..c39713243d 100644 --- a/src/derive.rs +++ b/src/derive.rs @@ -3,8 +3,7 @@ use crate::punctuated::Punctuated; ast_struct! { /// Data structure sent to a `proc_macro_derive` macro. - /// - /// *This type is available only if Syn is built with the `"derive"` feature.* + #[cfg_attr(docsrs, doc(cfg(feature = "derive")))] pub struct DeriveInput { /// Attributes tagged on the whole struct or enum. pub attrs: Vec, @@ -26,8 +25,6 @@ ast_struct! { ast_enum_of_structs! { /// The storage of a struct, enum or union data structure. /// - /// *This type is available only if Syn is built with the `"derive"` feature.* - /// /// # Syntax tree enum /// /// This type is a [syntax tree enum]. @@ -36,6 +33,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(docsrs, doc(cfg(feature = "derive")))] pub enum Data { /// A struct input to a `proc_macro_derive` macro. Struct(DataStruct), @@ -52,9 +50,7 @@ ast_enum_of_structs! { ast_struct! { /// A struct input to a `proc_macro_derive` macro. - /// - /// *This type is available only if Syn is built with the `"derive"` - /// feature.* + #[cfg_attr(docsrs, doc(cfg(feature = "derive")))] pub struct DataStruct { pub struct_token: Token![struct], pub fields: Fields, @@ -64,9 +60,7 @@ ast_struct! { ast_struct! { /// An enum input to a `proc_macro_derive` macro. - /// - /// *This type is available only if Syn is built with the `"derive"` - /// feature.* + #[cfg_attr(docsrs, doc(cfg(feature = "derive")))] pub struct DataEnum { pub enum_token: Token![enum], pub brace_token: token::Brace, @@ -76,9 +70,7 @@ ast_struct! { ast_struct! { /// An untagged union input to a `proc_macro_derive` macro. - /// - /// *This type is available only if Syn is built with the `"derive"` - /// feature.* + #[cfg_attr(docsrs, 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 ce87136e4c..41e591e598 100644 --- a/src/expr.rs +++ b/src/expr.rs @@ -14,9 +14,6 @@ use std::mem; ast_enum_of_structs! { /// A Rust expression. /// - /// *This type is available only if Syn is built with the `"derive"` or `"full"` - /// feature, but most of the variants are not available unless "full" is enabled.* - /// /// # Syntax tree enums /// /// This type is a syntax tree enum. In Syn this and other syntax tree enums @@ -86,6 +83,7 @@ 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(docsrs, doc(cfg(any(feature = "derive", feature = "full"))))] pub enum Expr #manual_extra_traits { /// A slice literal expression: `[a, b, c, d]`. Array(ExprArray), @@ -230,8 +228,7 @@ ast_enum_of_structs! { ast_struct! { /// A slice literal expression: `[a, b, c, d]`. - /// - /// *This type is available only if Syn is built with the `"full"` feature.* + #[cfg_attr(docsrs, doc(cfg(feature = "full")))] pub struct ExprArray #full { pub attrs: Vec, pub bracket_token: token::Bracket, @@ -241,8 +238,7 @@ ast_struct! { ast_struct! { /// An assignment expression: `a = compute()`. - /// - /// *This type is available only if Syn is built with the `"full"` feature.* + #[cfg_attr(docsrs, doc(cfg(feature = "full")))] pub struct ExprAssign #full { pub attrs: Vec, pub left: Box, @@ -253,8 +249,7 @@ ast_struct! { ast_struct! { /// A compound assignment expression: `counter += 1`. - /// - /// *This type is available only if Syn is built with the `"full"` feature.* + #[cfg_attr(docsrs, doc(cfg(feature = "full")))] pub struct ExprAssignOp #full { pub attrs: Vec, pub left: Box, @@ -265,8 +260,7 @@ ast_struct! { ast_struct! { /// An async block: `async { ... }`. - /// - /// *This type is available only if Syn is built with the `"full"` feature.* + #[cfg_attr(docsrs, doc(cfg(feature = "full")))] pub struct ExprAsync #full { pub attrs: Vec, pub async_token: Token![async], @@ -277,8 +271,7 @@ ast_struct! { ast_struct! { /// An await expression: `fut.await`. - /// - /// *This type is available only if Syn is built with the `"full"` feature.* + #[cfg_attr(docsrs, doc(cfg(feature = "full")))] pub struct ExprAwait #full { pub attrs: Vec, pub base: Box, @@ -289,9 +282,7 @@ ast_struct! { ast_struct! { /// A binary operation: `a + b`, `a * b`. - /// - /// *This type is available only if Syn is built with the `"derive"` or - /// `"full"` feature.* + #[cfg_attr(docsrs, doc(cfg(any(feature = "derive", feature = "full"))))] pub struct ExprBinary { pub attrs: Vec, pub left: Box, @@ -302,8 +293,7 @@ ast_struct! { ast_struct! { /// A blocked scope: `{ ... }`. - /// - /// *This type is available only if Syn is built with the `"full"` feature.* + #[cfg_attr(docsrs, doc(cfg(feature = "full")))] pub struct ExprBlock #full { pub attrs: Vec, pub label: Option