parse_nested_meta docs: mention that error will be returned if closure doesn't parse non-path parts

[nicholasbishop]

I tried using parse_nested_meta for something very similar to the repr-parsing example given in the docs, except that I didn't need all the information. I was confused why parse_nested_meta returned an error sometimes, even though the closure I passed in did not return an error, and the repr being parsed was valid. I eventually realized that this is because I wasn't parsing the (N) part of align(N). Simplified example:

use anyhow::Result;
use syn::{parenthesized, parse_quote, ItemStruct, LitInt};

fn main() -> Result<()> {
    let input: ItemStruct = parse_quote! {
        #[repr(C, align(4))]
        pub struct MyStruct(u16, u32);
    };

    let mut repr_align = false;
    for attr in &input.attrs {
        if attr.path().is_ident("repr") {
            attr.parse_nested_meta(|meta| {
                if meta.path.is_ident("align") {
                    // With this uncommented, no error occurs:
                    //    let content;
                    //    parenthesized!(content in meta.input);
                    //    let lit: LitInt = content.parse()?;

                    repr_align = true;
                    return Ok(());
                }

                Ok(())
            })
            .unwrap();
        }
    }

    Ok(())
}

Assuming that this is the intended behavior of parse_nested_meta, it would be helpful to describe in the docs exactly what the closure needs to handle itself in order to avoid parse_nested_meta returning an error.

[loganmzz]

Will also be nice to improve error message: https://play.rust-lang.org/?version=stable&mode=debug&edition=2021&gist=143d258548b205268c85cd1e38dedae9

[Kayanski]

I ran into this issue just now and I can say this is a big pain. Here are some reasons :

• Because meta.input is not mutable explicitly, it's difficult to understand that input can be mutated inside the function
• Because you might want to parse for certain attributes at a time (this issue is related : Can not parse attribute with multiple arguments using parse_nested_meta #1411)
• Because the error you get is not really helpful

[nazar-pc]

I also suffered some from parse_nested_meta. I was trying to parse #[repr()] just to check that it starts with #[repr(C or #[repr(transparent:

let mut checked = false;

if let Err(error) = repr_attr.parse_nested_meta(|meta| {
    if checked || meta.path.is_ident("C") || meta.path.is_ident("transparent") {
        checked = true;

        Ok(())
    } else {
        Err(Error::new(
            input.ident.span(),
            "`IoType` on structs requires `#[repr(C)]` or `#[repr(transparent)]",
        ))
    }
}) {
    return error.to_compile_error().into();
}

However, failure to parse all possible cases results in confusing error, like this:

error: expected `,`
  --> .../src/lib.rs:98:16
   |
98 | #[repr(C, align(32))]

Even though as described above my handler didn't return any errors. I have not found more ergonomic ways to parse it either.