Rollup merge of rust-lang#132642 - GuillaumeGomez:attr-docs, r=compiler-errors

Add documentation on `ast::Attribute`

I was working again with attributes in clippy recently and I often find myself in need to read the source code to ensure it's doing what I want.

Instead, a bit of documentation would allow me (and hopefully others) to skip this step.

Author: matthiaskrgr

compiler/rustc_ast/src/attr/mod.rs

@@ -136,13 +136,35 @@ impl Attribute {
         }
     }
 
+    /// Returns a list of meta items if the attribute is delimited with parenthesis:
+    ///
+    /// ```text
+    /// #[attr(a, b = "c")] // Returns `Some()`.
+    /// #[attr = ""] // Returns `None`.
+    /// #[attr] // Returns `None`.
+    /// ```
     pub fn meta_item_list(&self) -> Option<ThinVec<MetaItemInner>> {
         match &self.kind {
             AttrKind::Normal(normal) => normal.item.meta_item_list(),
             AttrKind::DocComment(..) => None,
         }
     }
 
+    /// Returns the string value in:
+    ///
+    /// ```text
+    /// #[attribute = "value"]
+    ///               ^^^^^^^
+    /// ```
+    ///
+    /// It returns `None` in any other cases, including doc comments if they
+    /// are not under the form `#[doc = "..."]`.
+    ///
+    /// It also returns `None` for:
+    ///
+    /// ```text
+    /// #[attr("value")]
+    /// ```
     pub fn value_str(&self) -> Option<Symbol> {
         match &self.kind {
             AttrKind::Normal(normal) => normal.item.value_str(),
@@ -232,6 +254,18 @@ impl AttrItem {
         }
     }
 
+    /// Returns the string value in:
+    ///
+    /// ```text
+    /// #[attribute = "value"]
+    ///               ^^^^^^^
+    /// ```
+    ///
+    /// It returns `None` in any other cases like:
+    ///
+    /// ```text
+    /// #[attr("value")]
+    /// ```
     fn value_str(&self) -> Option<Symbol> {
         match &self.args {
             AttrArgs::Eq(_, args) => args.value_str(),
@@ -315,6 +349,18 @@ impl MetaItem {
         Some(self.name_value_literal()?.span)
     }
 
+    /// Returns the string value in:
+    ///
+    /// ```text
+    /// #[attribute = "value"]
+    ///               ^^^^^^^
+    /// ```
+    ///
+    /// It returns `None` in any other cases like:
+    ///
+    /// ```text
+    /// #[attr("value")]
+    /// ```
     pub fn value_str(&self) -> Option<Symbol> {
         match &self.kind {
             MetaItemKind::NameValue(v) => v.kind.str(),