Add documentation for higher-level attribute parsing API

compiler/rustc_attr_parsing/src/context.rs

@@ -572,6 +572,20 @@ pub(crate) fn expect_single_element_list<'arg>(
         Some(single)
     }
 
+    /// Asserts that an [`ArgParser`] is a list and returns it, or emits an error and returns
+    /// `None`.
+    ///
+    /// Some examples:
+    ///
+    /// - `#[allow(clippy::complexity)]`: `(clippy::complexity)` is a list
+    /// - `#[rustfmt::skip::macros(target_macro_name)]`: `(target_macro_name)` is a list
+    ///
+    /// This is a higher-level (and harder to misuse) wrapper over [`ArgParser::as_list`]. That
+    /// allows using `?` when the attribute parsing function allows it. You may still want to use
+    /// [`ArgParser::as_list`] for the following reasons:
+    ///
+    /// - You want to emit your own diagnostics (for instance, with [`SharedContext::emit_err`]).
+    /// - The attribute can be parsed in multiple ways and it does not make sense to emit an error.
     pub(crate) fn expect_list<'arg>(
         &mut self,
         args: &'arg ArgParser,
@@ -584,6 +598,15 @@ pub(crate) fn expect_list<'arg>(
         list
     }
 
+    /// Asserts that a [`MetaItemListParser`] contains a single element and returns it, or emits an
+    /// error and returns `None`.
+    ///
+    /// This is a higher-level (and harder to misuse) wrapper over [`MetaItemListParser::as_single`].
+    /// That allows using `?` to early return. You may still want to use
+    /// [`MetaItemListParser::as_single`] for the following reasons:
+    ///
+    /// - You want to emit your own diagnostics (for instance, with [`SharedContext::emit_err`]).
+    /// - The attribute can be parsed in multiple ways and it does not make sense to emit an error.
     pub(crate) fn expect_single<'arg>(
         &mut self,
         list: &'arg MetaItemListParser,

compiler/rustc_attr_parsing/src/parser.rs

@@ -255,6 +255,7 @@ pub fn meta_item(&self) -> Option<&MetaItemParser> {
     }
 }
 
+// FIXME(scrabsha): once #155696 is merged, update this and mention the higher-level APIs.
 /// Utility that deconstructs a MetaItem into usable parts.
 ///
 /// MetaItems are syntactically extremely flexible, but specific attributes want to parse
@@ -263,7 +264,7 @@ pub fn meta_item(&self) -> Option<&MetaItemParser> {
 /// MetaItems consist of some path, and some args. The args could be empty. In other words:
 ///
 /// - `name` -> args are empty
-/// - `name(...)` -> args are a [`list`](ArgParser::list), which is the bit between the parentheses
+/// - `name(...)` -> args are a [`list`](ArgParser::as_list), which is the bit between the parentheses
 /// - `name = value`-> arg is [`name_value`](ArgParser::name_value), where the argument is the
 ///   `= value` part
 ///