Add a higher-level API for parsing attributes

[scrabsha]

I got quite frustrated that a lot of the attribute parsing API repeats the same pattern over and over:

let Some(list) = args.list() else {
    cx.expected_list(args, span);
    return None;
}

(Example uses list, but this happens to most of the methods in rustc_attr_parsing::parser actually)

Besides the repetitions, here's why I don't like it:

• It separates the checks on the attribute arguments with the error emission
• Early returns are explicit and take a lot of space
• It is quite easy to accidentally generate an error message that has little to do with the check that has just been done (I already fixed things in 1, 2)
• I am convinced that APIs that require too much boilerplate and repetitions give people an incentive to use Automated Code Generation Tools ™️ and I would like to avoid giving this incentive.

This PR adds an AcceptContext::expect_list method, allowing to replace the code in the previous snippet with:

let list = cx.expect_list(args, span)?;

which I believe solves the concerns I wrote earlier.

I already introduced an AcceptContext::expect_single_element_list method that follows similar style in #154827, and ideally I would like this PR to generalize this idea.

I do not expect this higher-level API to replace the methods in rustc_attr_parsing::parser, but rather to provide a higher-level version that can be used in most simple situations. This is explained both in the documentation added in this PR and in #154827 (comment).

In the long term, I also hope we could make AcceptContext::expect_list and friends push custom suggestions to the diagnostics and hopefully stop relying on the attribute template in future.

The first commit introduces AcceptContext::expect_list and AcceptContext::expect_single and uses it where it makes sense to. I added only these two because I figured it would be a nice way to ask for feedback without investing too much time. The second commit adds documentation for the newly added methods.

@JonathanBrouwer I think you're the best person to ask feedback from, let me know what you think!

---

I also tried to make the parsing functions return a Result<Self, ErrorGuaranteed>, but I don't think it is possible due to Combine::finalize

[rustbot]

Reminder, once the PR becomes ready for a review, use @rustbot ready.

[rustbot]

Some changes occurred in compiler/rustc_attr_parsing

cc @jdonszelmann, @JonathanBrouwer

Some changes occurred to diagnostic attributes.

cc @mejrs

[scrabsha]

It felt wrong to mention AcceptContext::expect_list/AcceptContext::expect_single here given that the other functions don't exist yet. If that's good for you, I'll update this doc comment once all the AcceptContext::expect_* functions are implemented.

[scrabsha]

@JonathanBrouwer so this PR renames list -> as_list and single -> as_single. should I immediately rename every method in parser.rs or is it ok if I only rename the other methods as I implement their replacement?

(I don't really have an opinion on what is better, it's up to you ^^)

[JonathanBrouwer]

@bors r+ rollup

View changes since this review

[rust-bors]

📌 Commit 067ef3d has been approved by JonathanBrouwer

It is now in the queue for this repository.