Documentation for Attribute
diff --git a/src/attr.rs b/src/attr.rs
index 1233663..393ffc8 100644
--- a/src/attr.rs
+++ b/src/attr.rs
@@ -19,24 +19,48 @@
use tt::TokenStreamHelper;
ast_struct! {
- /// Doc-comments are promoted to attributes that have `is_sugared_doc` = true
+ /// An attribute like `#[repr(transparent)]`.
+ ///
+ /// # Syntax
+ ///
+ /// Rust has six types of attributes.
+ ///
+ /// - Outer attributes like `#[repr(transparent)]`. These appear outside or
+ /// in front of the item they describe.
+ /// - Inner attributes like `#![feature(proc_macro)]`. These appear inside
+ /// of the item they describe, usually a module.
+ /// - Outer doc comments like `/// # Example`.
+ /// - Inner doc comments like `//! Please file an issue`.
+ /// - Outer block comments `/** # Example */`.
+ /// - Inner block comments `/*! Please file an issue */`.
+ ///
+ /// The `style` field of type `AttrStyle` distinguishes whether an attribute
+ /// is outer or inner. Doc comments and block comments are promoted to
+ /// attributes that have `is_sugared_doc` set to true, as this is how they
+ /// are processed by the compiler and by `macro_rules!` macros.
+ ///
+ /// The `path` field gives the possibly colon-delimited path against which
+ /// the attribute is resolved. It is equal to `"doc"` for desugared doc
+ /// comments. The `tts` field contains the rest of the attribute body as
+ /// tokens.
+ ///
+ /// ```text
+ /// #[derive(Copy)] #[crate::precondition x < 5]
+ /// ^^^^^^~~~~~~ ^^^^^^^^^^^^^^^^^^^ ~~~~~
+ /// path tts path tts
+ /// ```
+ ///
+ /// Use the [`meta_item`] method to try parsing the tokens of an attribute
+ /// into the structured representation that is used by convention across
+ /// most Rust libraries.
+ ///
+ /// [`meta_item`]: #method.meta_item
pub struct Attribute #manual_extra_traits {
pub pound_token: Token![#],
pub style: AttrStyle,
pub bracket_token: token::Bracket,
-
- /// The path of the attribute.
- ///
- /// E.g. `derive` in `#[derive(Copy)]`
- /// E.g. `crate::precondition` in `#[crate::precondition x < 5]`
pub path: Path,
-
- /// Any tokens after the path.
- ///
- /// E.g. `( Copy )` in `#[derive(Copy)]`
- /// E.g. `x < 5` in `#[crate::precondition x < 5]`
pub tts: TokenStream,
-
pub is_sugared_doc: bool,
}
}
@@ -198,14 +222,22 @@
ast_enum! {
/// Distinguishes between Attributes that decorate items and Attributes that
- /// are contained as statements within items. These two cases need to be
- /// distinguished for pretty-printing.
+ /// are contained as statements within items.
+ ///
+ /// # Outer attributes
+ ///
+ /// - `#[repr(transparent)]`
+ /// - `/// # Example`
+ /// - `/** Please file an issue */`
+ ///
+ /// # Inner attributes
+ ///
+ /// - `#![feature(proc_macro)]`
+ /// - `//! # Example`
+ /// - `/*! Please file an issue */`
#[cfg_attr(feature = "clone-impls", derive(Copy))]
pub enum AttrStyle {
- /// Attribute of the form `#[...]`.
Outer,
-
- /// Attribute of the form `#![...]`.
Inner(Token![!]),
}
}