Refactor rustc_attr_data_structures documentation

Signed-off-by: xizheyin <[email protected]>

Author: xizheyin

compiler/rustc_attr_data_structures/src/attributes.rs

@@ -138,59 +138,171 @@ impl Deprecation {
     }
 }
 
-/// Represent parsed, *built in*, inert attributes.
+/// Represents parsed *built-in* inert attributes.
 ///
-/// That means attributes that are not actually ever expanded.
-/// For more information on this, see the module docs on the [`rustc_attr_parsing`] crate.
-/// They're instead used as markers, to guide the compilation process in various way in most every stage of the compiler.
-/// These are kept around after the AST, into the HIR and further on.
+/// ## Overview
+/// These attributes are markers that guide the compilation process and are never expanded into other code.
+/// They persist throughout the compilation phases, from AST to HIR and beyond.
 ///
-/// The word "parsed" could be a little misleading here, because the parser already parses
-/// attributes early on. However, the result, an [`ast::Attribute`]
-/// is only parsed at a high level, still containing a token stream in many cases. That is
-/// because the structure of the contents varies from attribute to attribute.
-/// With a parsed attribute I mean that each attribute is processed individually into a
-/// final structure, which on-site (the place where the attribute is useful for, think the
-/// the place where `must_use` is checked) little to no extra parsing or validating needs to
-/// happen.
+/// ## Attribute Processing
+/// While attributes are initially parsed into [`ast::Attribute`], they still contain raw token streams
+/// because different attributes have different internal structures. This enum represents the final,
+/// fully parsed form of these attributes, where each variant contains all necessary information
+/// in a structured format.
 ///
-/// For more docs, look in [`rustc_attr_parsing`].
+/// ## Usage
+/// These parsed attributes are used throughout the compiler to:
+/// - Control code generation (e.g., `#[repr]`)
+/// - Mark API stability (`#[stable]`, `#[unstable]`)
+/// - Provide documentation (`#[doc]`)
+/// - Guide compiler behavior (e.g., `#[allow_internal_unstable]`)
 ///
+/// ## Note on Attribute Organization
+/// Some attributes like `InlineAttr`, `OptimizeAttr`, and `InstructionSetAttr` are defined separately
+/// from this enum because they are used in specific compiler phases (like code generation) and don't
+/// need to persist throughout the entire compilation process. They are typically processed and
+/// converted into their final form earlier in the compilation pipeline.
+///
+/// For example:
+/// - `InlineAttr` is used during code generation to control function inlining
+/// - `OptimizeAttr` is used to control optimization levels
+/// - `InstructionSetAttr` is used for target-specific code generation
+///
+/// These attributes are handled by their respective compiler passes in the [`rustc_codegen_ssa`] crate
+/// and don't need to be preserved in the same way as the attributes in this enum.
+///
+/// For more details on attribute parsing, see the [`rustc_attr_parsing`] crate.
+///
+/// [`rustc_codegen_ssa`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_codegen_ssa/index.html
 /// [`rustc_attr_parsing`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_attr_parsing/index.html
 #[derive(Clone, Debug, HashStable_Generic, Encodable, Decodable, PrintAttribute)]
 pub enum AttributeKind {
     // tidy-alphabetical-start
+    /// Allows unstable features in const functions.
+    /// Contains a list of allowed feature names.
+    ///
+    /// # Example
+    /// ```rust
+    /// #[allow_internal_unstable(const_fn)]
+    /// ```
     AllowConstFnUnstable(ThinVec<Symbol>),
+
+    /// Allows internal unstable features.
+    /// Contains pairs of feature names and their spans.
+    ///
+    /// # Example
+    /// ```rust
+    /// #[allow_internal_unstable(feature1, feature2)]
+    /// ```
     AllowInternalUnstable(ThinVec<(Symbol, Span)>),
+
+    /// Marks the stability of a default body implementation.
+    /// Contains stability information and the attribute's span.
+    ///
+    /// # Example
+    /// ```rust
+    /// #[rustc_default_body_unstable(feature = "default_foo", issue = "12345")]
+    /// ```
     BodyStability {
         stability: DefaultBodyStability,
         /// Span of the `#[rustc_default_body_unstable(...)]` attribute
         span: Span,
     },
+
+    /// Marks confusable symbols.
+    /// Contains the symbols and the span of the first occurrence.
+    ///
+    /// # Example
+    /// ```rust
+    /// #[rustc_confusables("l", "I", "1")]
+    /// ```
     Confusables {
         symbols: ThinVec<Symbol>,
         // FIXME(jdonszelmann): remove when target validation code is moved
         first_span: Span,
     },
+
+    /// Marks the stability of const functions.
+    /// Contains stability information and the attribute's span.
+    ///
+    /// # Example
+    /// ```rust
+    /// #[rustc_const_stable(feature = "const_foo", since = "1.50.0")]
+    /// #[rustc_const_unstable(feature = "const_bar", issue = "12345")]
+    /// ```
     ConstStability {
         stability: PartialConstStability,
         /// Span of the `#[rustc_const_stable(...)]` or `#[rustc_const_unstable(...)]` attribute
         span: Span,
     },
+
+    /// Indicates indirect const stability.
+    ///
+    /// # Example
+    /// ```rust
+    /// #[rustc_const_stable(feature = "const_foo", since = "1.50.0")]
+    /// #[rustc_const_stable(feature = "const_bar", since = "1.50.0")]
+    /// ```
     ConstStabilityIndirect,
-    Deprecation {
-        deprecation: Deprecation,
-        span: Span,
-    },
+
+    /// Marks deprecated items.
+    /// Contains deprecation information and the attribute's span.
+    ///
+    /// # Example
+    /// ```rust
+    /// #[deprecated(since = "1.0.0", note = "Use new_function instead")]
+    /// ```
+    Deprecation { deprecation: Deprecation, span: Span },
+
+    /// Controls diagnostic behavior.
+    ///
+    /// # Example
+    /// ```rust
+    /// #[rustc_on_unimplemented(
+    ///     message = "the type `{Self}` cannot be indexed by `{Idx}`",
+    ///     label = "the type `{Self}` cannot be indexed by `{Idx}`"
+    /// )]
+    /// ```
     Diagnostic(DiagnosticAttribute),
-    DocComment {
-        style: AttrStyle,
-        kind: CommentKind,
-        span: Span,
-        comment: Symbol,
-    },
+
+    /// Represents documentation comments.
+    /// Contains the comment style, kind, span, and content.
+    ///
+    /// # Example
+    /// ```rust
+    /// /// This is a documentation comment
+    /// /// It can span multiple lines
+    /// #[doc = "This is also a doc comment"]
+    /// ```
+    DocComment { style: AttrStyle, kind: CommentKind, span: Span, comment: Symbol },
+
+    /// Controls macro transparency levels.
+    ///
+    /// # Example
+    /// ```rust
+    /// #[rustc_macro_transparency = "semitransparent"]
+    /// ```
     MacroTransparency(Transparency),
+
+    /// Controls type representation.
+    /// Contains a list of repr attributes and their spans.
+    ///
+    /// # Example
+    /// ```rust
+    /// #[repr(C)]
+    /// #[repr(packed)]
+    /// #[repr(align(8))]
+    /// ```
     Repr(ThinVec<(ReprAttr, Span)>),
+
+    /// Marks API stability.
+    /// Contains stability information and the attribute's span.
+    ///
+    /// # Example
+    /// ```rust
+    /// #[stable(feature = "rust1", since = "1.0.0")]
+    /// #[unstable(feature = "foo", issue = "12345")]
+    /// ```
     Stability {
         stability: Stability,
         /// Span of the `#[stable(...)]` or `#[unstable(...)]` attribute

compiler/rustc_attr_data_structures/src/lib.rs

@@ -1,3 +1,37 @@
+//! Data structures for representing parsed attributes in the Rust compiler.
+//!
+//! This crate is part of a series of crates that handle attribute processing:
+//! - [rustc_attr_data_structures](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_attr_data_structures/index.html): Defines the data structures that store parsed attributes
+//! - [rustc_attr_parsing](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_attr_parsing/index.html): Handles the parsing of attributes
+//! - (planned) rustc_attr_validation: Will handle attribute validation
+//!
+//! ## Overview
+//! This crate defines the data structures that represent attributes after they have been parsed.
+//! These structures are used throughout the compiler to store and process attribute information.
+//!
+//! ## Key Components
+//! - [`AttributeKind`]: The main enum that represents different types of built-in inert attributes
+//! - [`InlineAttr`]: Controls function inlining behavior
+//! - [`OptimizeAttr`]: Controls optimization levels
+//! - [`InstructionSetAttr`]: Controls target-specific code generation
+//!
+//! ## Attribute Organization
+//! Attributes in this crate are organized based on their usage in the compiler:
+//! - Attributes in [`AttributeKind`] are used throughout the compilation process
+//! - Other attributes (like [`InlineAttr`]) are used in specific compiler phases
+//!   and are handled by their respective passes in the [`rustc_codegen_ssa`] crate
+//!
+//! ## Related Crates
+//! - [`rustc_attr_parsing`]: Handles the parsing of attributes into these data structures
+//! - [`rustc_codegen_ssa`]: Uses some of these structures for code generation
+//!
+//! [`AttributeKind`]: attributes::AttributeKind
+//! [`InlineAttr`]: attributes::InlineAttr
+//! [`OptimizeAttr`]: attributes::OptimizeAttr
+//! [`InstructionSetAttr`]: attributes::InstructionSetAttr
+//! [`rustc_attr_parsing`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_attr_parsing/index.html
+//! [`rustc_codegen_ssa`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_codegen_ssa/index.html
+
 // tidy-alphabetical-start
 #![allow(internal_features)]
 #![doc(rust_logo)]