diagnostics: emit unused_doc_comments on fn nest

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 |     /// nested fn
      |     ^^^^^^^^^^^^^
    4 |     pub 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

Author: notriddle

compiler/rustc_lint/src/builtin.rs

@@ -838,6 +838,32 @@ impl EarlyLintPass for UnusedDocComment {
     fn check_item(&mut self, cx: &EarlyContext<'_>, item: &ast::Item) {
         if let ast::ItemKind::ForeignMod(_) = item.kind {
             warn_if_doc(cx, item.span, "extern blocks", &item.attrs);
+        } else if self.in_fn != 0 {
+            warn_if_doc(cx, item.span, "items defined in functions", &item.attrs);
+            fn warn_on_fields(cx: &EarlyContext<'_>, var_data: &VariantData) {
+                for field in var_data.fields() {
+                    warn_if_doc(cx, field.span, "fields defined nested in functions", &field.attrs);
+                }
+            }
+            if let ast::ItemKind::Struct(_, _, var_data) = &item.kind {
+                warn_on_fields(cx, var_data);
+            } else if let ast::ItemKind::Union(_, _, var_data) = &item.kind {
+                warn_on_fields(cx, var_data);
+            } else if let ast::ItemKind::Enum(_, _, def) = &item.kind {
+                for var in &def.variants {
+                    warn_if_doc(cx, var.span, "variants defined nested in functions", &var.attrs);
+                    warn_on_fields(cx, &var.data);
+                }
+            }
+        }
+        if let ast::ItemKind::Fn(_) = item.kind {
+            self.in_fn += 1;
+        }
+    }
+
+    fn check_item_post(&mut self, _: &EarlyContext<'_>, item: &ast::Item) {
+        if let ast::ItemKind::Fn(_) = item.kind {
+            self.in_fn -= 1;
         }
     }
 }

compiler/rustc_lint/src/lib.rs

@@ -184,7 +184,7 @@ early_lint_methods!(
             NonAsciiIdents: NonAsciiIdents,
             IncompleteInternalFeatures: IncompleteInternalFeatures,
             RedundantSemicolons: RedundantSemicolons,
-            UnusedDocComment: UnusedDocComment,
+            UnusedDocComment: UnusedDocComment::default(),
             Expr2024: Expr2024,
             Precedence: Precedence,
             DoubleNegations: DoubleNegations,

compiler/rustc_lint_defs/src/builtin.rs

@@ -7,7 +7,7 @@
 //! When removing a lint, make sure to also add a call to `register_removed` in
 //! compiler/rustc_lint/src/lib.rs.
 
-use crate::{declare_lint, declare_lint_pass, fcw};
+use crate::{declare_lint, fcw, impl_lint_pass};
 
 pub mod hardwired {
     use super::*;
@@ -3341,7 +3341,11 @@ declare_lint! {
     };
 }
 
-declare_lint_pass!(UnusedDocComment => [UNUSED_DOC_COMMENTS]);
+#[derive(Clone, Copy, Default)]
+pub struct UnusedDocComment {
+    pub in_fn: usize,
+}
+impl_lint_pass!(UnusedDocComment => [UNUSED_DOC_COMMENTS]);
 
 declare_lint! {
     /// The `missing_abi` lint detects cases where the ABI is omitted from