missing_docs_in_private_items requiring docs on function-local items

[connortsui20]

Summary

When turning on the missing_docs_in_private_items lint, items that exist within a function get caught for not having documentation comments, even though adding doc comments there would not emit any documentation anyways. I've seen that this is true for inner functions and macros, and it is probably true for all items that can be declared within a function.

I feel it doesn't make too much sense to require doc comments there since I don't think there is a way to even view them via cargo doc.

Lint Name

missing_docs_in_private_items

Reproducer

I tried this code:

//! Crate-level docs.

#![warn(clippy::missing_docs_in_private_items)]

/// Example docs.
pub fn example() {
    // Normal comments should be sufficient as doc comments won't get emitted anyways?
    fn private_fn() -> i32 {
        2 + 2
    }

    assert_eq!(private_fn(), 4);
    println!("Hello, world!");
}

I saw this happen:

❯ cargo clippy
warning: missing documentation for a function
  --> src/lib.rs:8:5
   |
8  | /     fn private_fn() -> i32 {
9  | |         2 + 2
10 | |     }
   | |_____^
   |
   = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#missing_docs_in_private_items
note: the lint level is defined here
  --> src/lib.rs:3:9
   |
3  | #![warn(clippy::missing_docs_in_private_items)]
   |         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

I expected to see no clippy warning.

Version

rustc 1.83.0 (90b35a623 2024-11-26)
binary: rustc
commit-hash: 90b35a6239c3d8bdabc530a6a0816f7ff89a0aaf
commit-date: 2024-11-26
host: x86_64-unknown-linux-gnu
release: 1.83.0
LLVM version: 19.1.1

Additional Labels

No response

[y21]

#13573 fixed this (no warning on nightly & beta), so the fix should be in the next release 1.84.0 (9th January)

it is probably true for all items that can be declared within a function

For what it's worth, impl trait blocks can be declared within functions and their documentation is visible, but my fix also stopped linting them because rustc will warn you to not do that anyway (non_local_definitions lint)