diagnostics: emit unused_doc_comments on fn nest

[notriddle]

When a doc comment is nested within an item:

fn foo() {
    /// doc comment
    fn bar() {}
}

When that happens, emit a warning, because they aren't rendered, even with --document-private-items

warning: unused doc comment
 --> src/lib.rs:3:3
  |
3 |     /// doc comment
  |     ^^^^^^^^^^^^^^^
4 |     fn bar() {}
  |     ----------- rustdoc does not generate documentation for items defined in functions
  |
  = help: use `//` for a plain comment
  = note: `#[warn(unused_doc_comments)]` (part of `#[warn(unused)]`) on by default

Fixes #158513

[rustbot]

compiler-builtins is developed in its own repository. If possible, consider making this change to rust-lang/compiler-builtins instead.

cc @tgross35

[rustbot]

r? @jackh726

rustbot has assigned @jackh726.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

Why was this reviewer chosen?

The reviewer was selected based on:

• Owners of files modified in this PR: compiler
• compiler expanded to 73 candidates
• Random selection from 18 candidates

[notriddle]

r? rustdoc

[GuillaumeGomez]

Please add a test for an impl inside a block to ensure it's not emitted for this case

View changes since the review

[GuillaumeGomez]

Looks all good, just one missing testcase.

View changes since this review

[rustbot]

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

[fmease]

The same holds for const items:

pub const X: () = { /** X */ pub fn x() {} };

const _: () = { /** X */ pub fn x() {} };

Ideally we would lint here, too, wouldn't we?

View changes since the review

[fmease]

Or rather anonymous constants in general:

type X = [(); { /** X */ pub fn x() {} 0 }];

[fmease]

but be careful about impls where we shouldn't fire even if nested in an anonymous constant / constant item:

const _: () = { /** X */ impl Trait for () {} };
pub trait Trait {}

Above, the doc comment does get rendered.

[fmease]

I believe this introduces false positives with impl blocks. Does your PR now warn on the following?

fn f() { /** X */ impl Trait for () {} }
pub trait Trait {}

Above, the doc comment does get rendered.

View changes since the review

[rustbot]

Some changes occurred to the CTFE / Miri interpreter

cc @rust-lang/miri, @RalfJung, @oli-obk, @lcnr

[RalfJung]

I don't think we should warn here. These doc comments are still useful: they are rendered by RA when hovering a call site. IOW they are pretty much exactly like a doc comment for a private item, and we don't warn against those either.

[rust-log-analyzer]

The job aarch64-gnu-llvm-21-1 failed! Check out the build log: (web) (plain enhanced) (plain)

Click to see the possible cause of the failure (guessed by this bot)

  --> compiler/rustc_ty_utils/src/layout/invariant.rs:38:5
   |
38 |       /// Yields non-ZST fields of the type
   |       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
39 | /     fn non_zst_fields<'tcx, 'a>(
40 | |         cx: &'a LayoutCx<'tcx>,
41 | |         layout: &'a TyAndLayout<'tcx>,
42 | |     ) -> impl Iterator<Item = (Size, TyAndLayout<'tcx>)> {
...  |
51 | |         })
52 | |     }
   | |_____- rustdoc does not generate documentation for items defined in functions
   |
---
   Compiling rustc_codegen_ssa v0.0.0 (/checkout/compiler/rustc_codegen_ssa)
warning: unused doc comment
   --> compiler/rustc_codegen_ssa/src/back/metadata.rs:425:5
    |
425 | /     /// The `object` crate demands "X.Y.Z encoded in nibbles as xxxx.yy.zz"
426 | |     /// e.g. minOS 14.0 = 0x000E0000, or SDK 16.2 = 0x00100200
    | |______________________________________________________________^
427 | /     fn pack_version(apple::OSVersion { major, minor, patch }: apple::OSVersion) -> u32 {
428 | |         let (major, minor, patch) = (major as u32, minor as u32, patch as u32);
429 | |         (major << 16) | (minor << 8) | patch
430 | |     }
    | |_____- rustdoc does not generate documentation for items defined in functions
    |
    = help: use `//` for a plain comment
    = note: `#[warn(unused_doc_comments)]` (part of `#[warn(unused)]`) on by default
---

warning: unused doc comment
   --> compiler/rustc_codegen_ssa/src/debuginfo/type_names.rs:464:5
    |
464 |       /// MSVC names enums differently than other platforms so that the debugging visualization
    |       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
...
468 | /     fn msvc_enum_fallback<'tcx>(
469 | |         tcx: TyCtxt<'tcx>,
470 | |         ty_and_layout: TyAndLayout<'tcx>,
471 | |         push_inner: &dyn Fn(/*output*/ &mut String, /*visited*/ &mut FxHashSet<Ty<'tcx>>),
...   |
478 | |         push_close_angle_bracket(true, output);
479 | |     }
    | |_____- rustdoc does not generate documentation for items defined in functions
    |