Auto merge of rust-lang#75776 - GuillaumeGomez:missing-doc-examples-l…

…int-improvements, r=jyn514

Missing doc examples lint improvements

Fixes rust-lang#75719.

To be merged after rust-lang#75718 (only the two last commits are from this PR).

Since you already reviewed rust-lang#75718, I'll set you as reviewer here as well. :)

r? @jyn514

src/librustdoc/passes/calculate_doc_coverage.rs

@@ -3,7 +3,7 @@ use crate::config::OutputFormat;
 use crate::core::DocContext;
 use crate::fold::{self, DocFolder};
 use crate::html::markdown::{find_testable_code, ErrorCodes};
-use crate::passes::doc_test_lints::Tests;
+use crate::passes::doc_test_lints::{should_have_doc_example, Tests};
 use crate::passes::Pass;
 use rustc_span::symbol::sym;
 use rustc_span::FileName;
@@ -231,19 +231,6 @@ impl fold::DocFolder for CoverageCalculator {
                 let has_docs = !i.attrs.doc_strings.is_empty();
                 let mut tests = Tests { found_tests: 0 };
 
-                let should_have_doc_examples = !matches!(i.inner,
-                    clean::StructFieldItem(_)
-                    | clean::VariantItem(_)
-                    | clean::AssocConstItem(_, _)
-                    | clean::AssocTypeItem(_, _)
-                    | clean::TypedefItem(_, _)
-                    | clean::StaticItem(_)
-                    | clean::ConstantItem(_)
-                    | clean::ExternCrateItem(_, _)
-                    | clean::ImportItem(_)
-                    | clean::PrimitiveItem(_)
-                    | clean::KeywordItem(_)
-                );
                 find_testable_code(
                     &i.attrs.doc_strings.iter().map(|d| d.as_str()).collect::<Vec<_>>().join("\n"),
                     &mut tests,
@@ -257,7 +244,7 @@ impl fold::DocFolder for CoverageCalculator {
                 self.items.entry(i.source.filename.clone()).or_default().count_item(
                     has_docs,
                     has_doc_example,
-                    should_have_doc_examples,
+                    should_have_doc_example(&i.inner),
                 );
             }
         }

src/librustdoc/passes/doc_test_lints.rs

@@ -4,6 +4,7 @@
 //! - PRIVATE_DOC_TESTS: this looks for private items with doc-tests.
 
 use super::{span_of_attrs, Pass};
+use crate::clean;
 use crate::clean::*;
 use crate::core::DocContext;
 use crate::fold::DocFolder;
@@ -59,6 +60,22 @@ impl crate::test::Tester for Tests {
     }
 }
 
+pub fn should_have_doc_example(item_kind: &clean::ItemEnum) -> bool {
+    !matches!(item_kind,
+        clean::StructFieldItem(_)
+        | clean::VariantItem(_)
+        | clean::AssocConstItem(_, _)
+        | clean::AssocTypeItem(_, _)
+        | clean::TypedefItem(_, _)
+        | clean::StaticItem(_)
+        | clean::ConstantItem(_)
+        | clean::ExternCrateItem(_, _)
+        | clean::ImportItem(_)
+        | clean::PrimitiveItem(_)
+        | clean::KeywordItem(_)
+    )
+}
+
 pub fn look_for_tests<'tcx>(cx: &DocContext<'tcx>, dox: &str, item: &Item) {
     let hir_id = match cx.as_local_hir_id(item.def_id) {
         Some(hir_id) => hir_id,
@@ -73,13 +90,7 @@ pub fn look_for_tests<'tcx>(cx: &DocContext<'tcx>, dox: &str, item: &Item) {
     find_testable_code(&dox, &mut tests, ErrorCodes::No, false, None);
 
     if tests.found_tests == 0 {
-        use ItemEnum::*;
-
-        let should_report = match item.inner {
-            ExternCrateItem(_, _) | ImportItem(_) | PrimitiveItem(_) | KeywordItem(_) => false,
-            _ => true,
-        };
-        if should_report {
+        if should_have_doc_example(&item.inner) {
             debug!("reporting error for {:?} (hir_id={:?})", item, hir_id);
             let sp = span_of_attrs(&item.attrs).unwrap_or(item.source.span());
             cx.tcx.struct_span_lint_hir(

src/test/rustdoc-ui/lint-missing-doc-code-example.rs

@@ -38,3 +38,34 @@ pub mod module3 {
   //~^ ERROR
   pub fn test() {}
 }
+
+/// Doc, but no code example and it's fine!
+pub const Const: u32 = 0;
+/// Doc, but no code example and it's fine!
+pub static Static: u32 = 0;
+/// Doc, but no code example and it's fine!
+pub type Type = u32;
+
+/// Doc
+//~^ ERROR
+pub struct Struct {
+    /// Doc, but no code example and it's fine!
+    pub field: u32,
+}
+
+/// Doc
+//~^ ERROR
+pub enum Enum {
+    /// Doc, but no code example and it's fine!
+    X,
+}
+
+/// Doc
+//~^ ERROR
+#[repr(C)]
+union Union {
+    /// Doc, but no code example and it's fine!
+    a: i32,
+    /// Doc, but no code example and it's fine!
+    b: f32,
+}

src/test/rustdoc-ui/lint-missing-doc-code-example.stderr

@@ -1,21 +1,39 @@
 error: missing code example in this documentation
-  --> $DIR/lint-missing-doc-code-example.rs:19:1
+  --> $DIR/lint-missing-doc-code-example.rs:49:1
    |
-LL | / mod module1 {
-LL | | }
-   | |_^
+LL | /// Doc
+   | ^^^^^^^
    |
 note: the lint level is defined here
   --> $DIR/lint-missing-doc-code-example.rs:2:9
    |
 LL | #![deny(missing_doc_code_examples)]
    |         ^^^^^^^^^^^^^^^^^^^^^^^^^
 
+error: missing code example in this documentation
+  --> $DIR/lint-missing-doc-code-example.rs:63:1
+   |
+LL | /// Doc
+   | ^^^^^^^
+
+error: missing code example in this documentation
+  --> $DIR/lint-missing-doc-code-example.rs:56:1
+   |
+LL | /// Doc
+   | ^^^^^^^
+
+error: missing code example in this documentation
+  --> $DIR/lint-missing-doc-code-example.rs:19:1
+   |
+LL | / mod module1 {
+LL | | }
+   | |_^
+
 error: missing code example in this documentation
   --> $DIR/lint-missing-doc-code-example.rs:37:3
    |
 LL |   /// doc
    |   ^^^^^^^
 
-error: aborting due to 2 previous errors
+error: aborting due to 5 previous errors