[DISCUSSIONS NEEDED] Add documentation for higher-level attribute parsing API

Author: scrabsha

compiler/rustc_attr_parsing/src/context.rs

@@ -572,6 +572,20 @@ impl<'f, 'sess: 'f, S: Stage> AcceptContext<'f, 'sess, S> {
         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::list`]. That allows
+    /// using `?` when the attribute parsing function allows it.  You may still want to use
+    /// [`ArgParser::list`] for the following reasons:
+    ///
+    /// - You want to emit your own diagnostics (for instance, with [`AcceptContext::emit_err`]).
+    /// - The attribute can be parsed in multiple ways and it does not make sense to emit an error.
     pub(crate) fn list<'arg>(
         &mut self,
         args: &'arg ArgParser,
@@ -584,6 +598,15 @@ impl<'f, 'sess: 'f, S: Stage> AcceptContext<'f, 'sess, S> {
         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::single`].
+    /// That allows using `?` to early return. You may still want to use
+    /// [`MetaItemListParser::single`] for the following reasons:
+    ///
+    /// - You want to emit your own diagnostics (for instance, with [`AcceptContext::emit_err`]).
+    /// - The attribute can be parsed in multiple ways and it does not make sense to emit an error.
     pub(crate) fn single<'arg>(
         &mut self,
         list: &'arg MetaItemListParser,