Apply unused_doc_comments lint to inner items

[Aaron1011]

Split out from #78306

The unused_doc_comments lint fires on comments that are not rendered by rustdoc. Currently, this fires on all non-item statements:

fn main() {
    /// Doc comment // warning: unused doc comment
    let _ = 1; 
    
    /// Other doc comment // warning: unused doc comment
    ()
}

However, we do not currently lint item statements:

fn main() {
	/// Doc comment, no warning
	fn inner() {}

	/// Another doc comment, no warning
	struct Foo {}
}

None of these doc comments will get rendered by rustdoc. However, as commit d12ea6e (#78367) shows, these kind of doc comments occur in many places throughout rustc. It's possibile this pattern is used in the wider ecosystem.

We have two options here, depending on what we think the meaning of doc comments should be:

1. Doc comments are an instruction to rustdoc to render something. We should lint doc comments on inner items - users should write regular comments instead, since they will not be rendered by rustdoc.
2. Doc comments are information for the user of an item (e.g. the caller of a function), which may get rendered as a result of running rustdoc. We should not lint doc comments on inner items, as they serve as a visual indicator to people reading the code. This is opposed to regular comments, which are primarily intended for people modifying a particular piece of code.

I don't have a strong preference as to which interpretation is correct. However, I think we should decide on one of them, and document the decision somewhere.

The current behavior of not linting item statements appears to have come about by accident. There was code in the lint that explicitly checked for StmtKind::Item, but it was never run due to a bug (fixed in #78326) with how we handled attributes on statements.

[rust-highfive]

r? @matthewjasper

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

[bors]

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

Note that reviewers usually do not review pull requests until merge conflicts are resolved! Once you resolve the conflicts, you should change the labels applied by bors to indicate that your PR is ready for review. Post this as a comment to change the labels:

@rustbot modify labels: +S-waiting-on-review -S-waiting-on-author

[matthewjasper]

cc @petrochenkov who reviewed #78306

[nikomatsakis]

Doc comments are information for the user of an item (e.g. the caller of a function), which may get rendered as a result of running rustdoc. We should not lint doc comments on inner items, as they serve as a visual indicator to people reading the code. This is opposed to regular comments, which are primarily intended for people modifying a particular piece of code.

This is how I feel. I would be quite surprised to see warnings here, the same as I would be surprised to see warnings on private or doc(hidden) items, even though those things may not be rendered in rustdoc.

I think I would want the property in particular that anything which is legal on a struct Foo definition at top-level is also legal on such a definition within a function.

[nikomatsakis]

@rfcbot fcp close

We discussed this in recent @rust-lang/lang meetings and decided that we felt that we did not want to warn for doc comments attached to inner items, just as we do not warn for doc comments on private functions or other things that may or may not appear in rustdoc output. Therefore, I'm moving to close the issue.

[rfcbot]

Team member @nikomatsakis has proposed to close this. The next step is review by the rest of the tagged team members:

• @cramertj
• @joshtriplett
• @nikomatsakis
• @pnkfelix
• @scottmcm
• @withoutboats

No concerns currently listed.

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

[nikomatsakis]

I checked the names of folks who were present in the meeting.

[rfcbot]

🔔 This is now entering its final comment period, as per the review above. 🔔

[nikomatsakis]

@rfcbot reviewed

[rfcbot]

The final comment period, with a disposition to close, as per the review above, is now complete.

As the automated representative of the governance process, I would like to thank the author for their work and everyone else who contributed.