overhaul unused doc comments lint

[euclio]

This PR contains a number of improvements to the unused_doc_comments lint.

• Extends the span to cover the entire comment when using sugared doc comments.
• Triggers the lint for all unused doc comments on a node, instead of just the first one.
• Triggers the lint on macro expansions, and provides a help note explaining that doc comments must be expanded by the macro.
• Adds a label pointing at the node that cannot be documented.

Furthermore, this PR fixes any instances in rustc where a macro expansion was erroneously documented.

[rust-highfive]

r? @michaelwoerister

(rust_highfive has picked a reviewer for you, use r? to override)

[michaelwoerister]

r? @estebank

[estebank]

@bors r+

[bors]

📌 Commit 871e460 has been approved by estebank

[bors]

☔️ The latest upstream changes (presumably #57726) made this pull request unmergeable. Please resolve the merge conflicts.

[bors]

🔒 Merge conflict

This pull request and the master branch diverged in a way that cannot be automatically merged. Please rebase on top of the latest master branch, and let the reviewer approve again.

How do I rebase?

Assuming self is your fork and upstream is this repository, you can resolve the conflict following these steps:

1. git checkout unused-doc-attributes (switch to your branch)
2. git fetch upstream master (retrieve the latest master)
3. git rebase upstream/master -p (rebase on top of it)
4. Follow the on-screen instruction to resolve conflicts (check git status if you got lost).
5. git push self unused-doc-attributes --force-with-lease (update this PR)

You may also read Git Rebasing to Resolve Conflicts by Drew Blessing for a short tutorial.

Please avoid the "Resolve conflicts" button on GitHub. It uses git merge instead of git rebase which makes the PR commit history more difficult to read.

Sometimes step 4 will complete without asking for resolution. This is usually due to difference between how Cargo.lock conflict is handled during merge and rebase. This is normal, and you should still perform step 5 to update this PR.

Error message

Auto-merging src/librustc_lint/lib.rs
CONFLICT (content): Merge conflict in src/librustc_lint/lib.rs
Auto-merging src/librustc_lint/builtin.rs
Auto-merging src/librustc/ty/mod.rs
Auto-merging src/librustc/ty/context.rs
Auto-merging src/librustc/hir/mod.rs
Auto-merging src/libcore/num/mod.rs
Automatic merge failed; fix conflicts and then commit the result.

[euclio]

@estebank Rebased.

[estebank]

@bors try

@euclio let's verify how much this change will impact the ecosystem before we merge.

[bors]

⌛️ Trying commit 75d30fd with merge 58c1b81...

[bors]

☀️ Test successful - checks-travis
State: approved= try=True

[euclio]

@estebank rebased. Did we ever get a crater run going for this?

[bors]

☔️ The latest upstream changes (presumably #58316) made this pull request unmergeable. Please resolve the merge conflicts.

[euclio]

@estebank Rebased.

[estebank]

Did we ever get a crater run going for this?

No we didn't, sorry about that, but the prior try run should be representative enough that we don't need to run it again.

@craterbot run start=master#da6ab956e1002517803ecd38b904504a1223274b end=try#58c1b81ef6055246e8b6467f767b2e3c1ce4403b

[craterbot]

👌 Experiment pr-57882 created and queued.
🔍 You can check out the queue and this experiment's details.

ℹ️ Crater is a tool to run experiments across parts of the Rust ecosystem. Learn more

[bors]

☔️ The latest upstream changes (presumably #58341) made this pull request unmergeable. Please resolve the merge conflicts.

[craterbot]

🚧 Experiment pr-57882 is now running on agent aws-1.

ℹ️ Crater is a tool to run experiments across parts of the Rust ecosystem. Learn more

[craterbot]

🎉 Experiment pr-57882 is completed!
📊 32 regressed and 19 fixed (50551 total)
📰 Open the full report.

⚠️ If you notice any spurious failure please add them to the blacklist!
ℹ️ Crater is a tool to run experiments across parts of the Rust ecosystem. Learn more

[estebank]

The breakage is remarkably small. @euclio would you mind contacting the crates that are confirmed to be broken by this (like carboxyl and biscuit) with either tickets or PRs nudging them in the right direction before we merge?

[euclio]

Sure thing.