Rollup merge of #133595 - GuillaumeGomez:missing_doc_code_examples, r=notriddle

Do not emit `missing_doc_code_examples` rustdoc lint on module and a few other items

It doesn't make sense to expect modules to have code examples. Same goes for:

 * Trait aliases
 * Foreign items
 * Associated types and constants

Should make the use of this lint a bit nicer.

r? ``@notriddle``

13 files changed, 39 insertions, 64 deletions

diff --git a/src/doc/rustdoc/src/unstable-features.md b/src/doc/rustdoc/src/unstable-features.md
index e9524c0b78d..db8426492ee 100644
--- a/src/doc/rustdoc/src/unstable-features.md
+++ b/src/doc/rustdoc/src/unstable-features.md
@@ -47,6 +47,10 @@ It can be enabled using:
 #![deny(rustdoc::missing_doc_code_examples)]
 ```
 
+It is not emitted for items that cannot be instantiated/called such as fields, variants, modules,
+associated trait/impl items, impl blocks, statics and constants.
+It is also not emitted for foreign items, aliases, extern crates and imports.
+
 ## Extensions to the `#[doc]` attribute
 
 These features operate by extending the `#[doc]` attribute, and thus can be caught by the compiler
diff --git a/src/librustdoc/passes/check_doc_test_visibility.rs b/src/librustdoc/passes/check_doc_test_visibility.rs
index bf851b278b8..c288a3cf2a4 100644
--- a/src/librustdoc/passes/check_doc_test_visibility.rs
+++ b/src/librustdoc/passes/check_doc_test_visibility.rs
@@ -60,8 +60,6 @@ pub(crate) fn should_have_doc_example(cx: &DocContext<'_>, item: &clean::Item) -
             item.kind,
             clean::StructFieldItem(_)
                 | clean::VariantItem(_)
-                | clean::AssocConstItem(..)
-                | clean::AssocTypeItem(..)
                 | clean::TypeAliasItem(_)
                 | clean::StaticItem(_)
                 | clean::ConstantItem(..)
@@ -69,6 +67,15 @@ pub(crate) fn should_have_doc_example(cx: &DocContext<'_>, item: &clean::Item) -
                 | clean::ImportItem(_)
                 | clean::PrimitiveItem(_)
                 | clean::KeywordItem
+                | clean::ModuleItem(_)
+                | clean::TraitAliasItem(_)
+                | clean::ForeignFunctionItem(..)
+                | clean::ForeignStaticItem(..)
+                | clean::ForeignTypeItem
+                | clean::AssocConstItem(..)
+                | clean::AssocTypeItem(..)
+                | clean::TyAssocConstItem(..)
+                | clean::TyAssocTypeItem(..)
                 // check for trait impl
                 | clean::ImplItem(box clean::Impl { trait_: Some(_), .. })
         )
diff --git a/tests/rustdoc-ui/coverage/doc-examples-json.stdout b/tests/rustdoc-ui/coverage/doc-examples-json.stdout
index 92f58556975..070fed0783e 100644
--- a/tests/rustdoc-ui/coverage/doc-examples-json.stdout
+++ b/tests/rustdoc-ui/coverage/doc-examples-json.stdout
@@ -1 +1 @@
-{"$DIR/doc-examples-json.rs":{"total":3,"with_docs":2,"total_examples":2,"with_examples":1}}
+{"$DIR/doc-examples-json.rs":{"total":3,"with_docs":2,"total_examples":1,"with_examples":1}}
diff --git a/tests/rustdoc-ui/coverage/doc-examples.stdout b/tests/rustdoc-ui/coverage/doc-examples.stdout
index 8188740f873..793adeb3518 100644
--- a/tests/rustdoc-ui/coverage/doc-examples.stdout
+++ b/tests/rustdoc-ui/coverage/doc-examples.stdout
@@ -1,7 +1,7 @@
 +-------------------------------------+------------+------------+------------+------------+
 | File                                | Documented | Percentage |   Examples | Percentage |
 +-------------------------------------+------------+------------+------------+------------+
-| ...tdoc-ui/coverage/doc-examples.rs |          4 |     100.0% |          1 |      25.0% |
+| ...tdoc-ui/coverage/doc-examples.rs |          4 |     100.0% |          1 |      33.3% |
 +-------------------------------------+------------+------------+------------+------------+
-| Total                               |          4 |     100.0% |          1 |      25.0% |
+| Total                               |          4 |     100.0% |          1 |      33.3% |
 +-------------------------------------+------------+------------+------------+------------+
diff --git a/tests/rustdoc-ui/coverage/json.stdout b/tests/rustdoc-ui/coverage/json.stdout
index c2be73ce3ed..25fd896baf1 100644
--- a/tests/rustdoc-ui/coverage/json.stdout
+++ b/tests/rustdoc-ui/coverage/json.stdout
@@ -1 +1 @@
-{"$DIR/json.rs":{"total":17,"with_docs":12,"total_examples":15,"with_examples":6}}
+{"$DIR/json.rs":{"total":17,"with_docs":12,"total_examples":13,"with_examples":6}}
diff --git a/tests/rustdoc-ui/lints/check.rs b/tests/rustdoc-ui/lints/check.rs
index 391ba517077..058c5d6c468 100644
--- a/tests/rustdoc-ui/lints/check.rs
+++ b/tests/rustdoc-ui/lints/check.rs
@@ -4,7 +4,6 @@
 
 #![feature(rustdoc_missing_doc_code_examples)]
 //~^ WARN
-//~^^ WARN
 
 #![warn(missing_docs)]
 #![warn(rustdoc::missing_doc_code_examples)]
diff --git a/tests/rustdoc-ui/lints/check.stderr b/tests/rustdoc-ui/lints/check.stderr
index acdb8128443..f1f36e8830d 100644
--- a/tests/rustdoc-ui/lints/check.stderr
+++ b/tests/rustdoc-ui/lints/check.stderr
@@ -4,19 +4,20 @@ warning: missing documentation for the crate
 LL | / #![feature(rustdoc_missing_doc_code_examples)]
 LL | |
 LL | |
+LL | | #![warn(missing_docs)]
 ...  |
 LL | |
 LL | | pub fn foo() {}
    | |_______________^
    |
 note: the lint level is defined here
-  --> $DIR/check.rs:9:9
+  --> $DIR/check.rs:8:9
    |
 LL | #![warn(missing_docs)]
    |         ^^^^^^^^^^^^
 
 warning: missing documentation for a function
-  --> $DIR/check.rs:13:1
+  --> $DIR/check.rs:12:1
    |
 LL | pub fn foo() {}
    | ^^^^^^^^^^^^
@@ -26,34 +27,23 @@ warning: no documentation found for this crate's top-level module
    = help: The following guide may be of use:
            https://doc.rust-lang.org/$CHANNEL/rustdoc/how-to-write-documentation.html
 note: the lint level is defined here
-  --> $DIR/check.rs:11:9
+  --> $DIR/check.rs:10:9
    |
 LL | #![warn(rustdoc::all)]
    |         ^^^^^^^^^^^^
    = note: `#[warn(rustdoc::missing_crate_level_docs)]` implied by `#[warn(rustdoc::all)]`
 
 warning: missing code example in this documentation
-  --> $DIR/check.rs:5:1
+  --> $DIR/check.rs:12:1
    |
-LL | / #![feature(rustdoc_missing_doc_code_examples)]
-LL | |
-LL | |
-...  |
-LL | |
-LL | | pub fn foo() {}
-   | |_______________^
+LL | pub fn foo() {}
+   | ^^^^^^^^^^^^^^^
    |
 note: the lint level is defined here
-  --> $DIR/check.rs:10:9
+  --> $DIR/check.rs:9:9
    |
 LL | #![warn(rustdoc::missing_doc_code_examples)]
    |         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-warning: missing code example in this documentation
-  --> $DIR/check.rs:13:1
-   |
-LL | pub fn foo() {}
-   | ^^^^^^^^^^^^^^^
-
-warning: 5 warnings emitted
+warning: 4 warnings emitted
 
diff --git a/tests/rustdoc-ui/lints/doc-without-codeblock.rs b/tests/rustdoc-ui/lints/doc-without-codeblock.rs
index 86d7c83d335..ccb241d4037 100644
--- a/tests/rustdoc-ui/lints/doc-without-codeblock.rs
+++ b/tests/rustdoc-ui/lints/doc-without-codeblock.rs
@@ -1,4 +1,4 @@
-#![feature(rustdoc_missing_doc_code_examples)] //~ ERROR missing code example in this documentation
+#![feature(rustdoc_missing_doc_code_examples)]
 #![deny(rustdoc::missing_doc_code_examples)]
 
 /// Some docs.
@@ -6,7 +6,6 @@
 pub struct Foo;
 
 /// And then, the princess died.
-//~^ ERROR missing code example in this documentation
 pub mod foo {
     /// Or maybe not because she saved herself!
     //~^ ERROR missing code example in this documentation
diff --git a/tests/rustdoc-ui/lints/doc-without-codeblock.stderr b/tests/rustdoc-ui/lints/doc-without-codeblock.stderr
index ebf2a2d54f7..d230f160693 100644
--- a/tests/rustdoc-ui/lints/doc-without-codeblock.stderr
+++ b/tests/rustdoc-ui/lints/doc-without-codeblock.stderr
@@ -1,14 +1,8 @@
 error: missing code example in this documentation
-  --> $DIR/doc-without-codeblock.rs:1:1
+  --> $DIR/doc-without-codeblock.rs:10:5
    |
-LL | / #![feature(rustdoc_missing_doc_code_examples)]
-LL | | #![deny(rustdoc::missing_doc_code_examples)]
-LL | |
-LL | | /// Some docs.
-...  |
-LL | |     }
-LL | | }
-   | |_^
+LL |     /// Or maybe not because she saved herself!
+   |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    |
 note: the lint level is defined here
   --> $DIR/doc-without-codeblock.rs:2:9
@@ -17,22 +11,10 @@ LL | #![deny(rustdoc::missing_doc_code_examples)]
    |         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 error: missing code example in this documentation
-  --> $DIR/doc-without-codeblock.rs:8:1
-   |
-LL | /// And then, the princess died.
-   | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-error: missing code example in this documentation
-  --> $DIR/doc-without-codeblock.rs:11:5
-   |
-LL |     /// Or maybe not because she saved herself!
-   |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-error: missing code example in this documentation
   --> $DIR/doc-without-codeblock.rs:4:1
    |
 LL | /// Some docs.
    | ^^^^^^^^^^^^^^
 
-error: aborting due to 4 previous errors
+error: aborting due to 2 previous errors
 
diff --git a/tests/rustdoc-ui/lints/lint-missing-doc-code-example.rs b/tests/rustdoc-ui/lints/lint-missing-doc-code-example.rs
index 40f35728d79..8e5c31d50ed 100644
--- a/tests/rustdoc-ui/lints/lint-missing-doc-code-example.rs
+++ b/tests/rustdoc-ui/lints/lint-missing-doc-code-example.rs
@@ -17,7 +17,7 @@ pub fn test() {
 }
 
 #[allow(missing_docs)]
-pub mod module1 { //~ ERROR
+pub mod module1 {
 }
 
 #[allow(rustdoc::missing_doc_code_examples)]
diff --git a/tests/rustdoc-ui/lints/lint-missing-doc-code-example.stderr b/tests/rustdoc-ui/lints/lint-missing-doc-code-example.stderr
index f9331250154..22533b9816a 100644
--- a/tests/rustdoc-ui/lints/lint-missing-doc-code-example.stderr
+++ b/tests/rustdoc-ui/lints/lint-missing-doc-code-example.stderr
@@ -1,8 +1,8 @@
 error: missing code example in this documentation
-  --> $DIR/lint-missing-doc-code-example.rs:20:1
+  --> $DIR/lint-missing-doc-code-example.rs:38:3
    |
-LL | pub mod module1 {
-   | ^^^^^^^^^^^^^^^
+LL |   /// doc
+   |   ^^^^^^^
    |
 note: the lint level is defined here
   --> $DIR/lint-missing-doc-code-example.rs:3:9
@@ -11,12 +11,6 @@ LL | #![deny(rustdoc::missing_doc_code_examples)]
    |         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 error: missing code example in this documentation
-  --> $DIR/lint-missing-doc-code-example.rs:38:3
-   |
-LL |   /// doc
-   |   ^^^^^^^
-
-error: missing code example in this documentation
   --> $DIR/lint-missing-doc-code-example.rs:50:1
    |
 LL | /// Doc
@@ -34,5 +28,5 @@ error: missing code example in this documentation
 LL | /// Doc
    | ^^^^^^^
 
-error: aborting due to 5 previous errors
+error: aborting due to 4 previous errors
 
diff --git a/tests/rustdoc-ui/show-coverage-json.stdout b/tests/rustdoc-ui/show-coverage-json.stdout
index ed5b5a60212..e6e882b2c57 100644
--- a/tests/rustdoc-ui/show-coverage-json.stdout
+++ b/tests/rustdoc-ui/show-coverage-json.stdout
@@ -1 +1 @@
-{"$DIR/show-coverage-json.rs":{"total":2,"with_docs":1,"total_examples":2,"with_examples":1}}
+{"$DIR/show-coverage-json.rs":{"total":2,"with_docs":1,"total_examples":1,"with_examples":1}}
diff --git a/tests/rustdoc-ui/show-coverage.stdout b/tests/rustdoc-ui/show-coverage.stdout
index b3b7679771f..b9e0316545e 100644
--- a/tests/rustdoc-ui/show-coverage.stdout
+++ b/tests/rustdoc-ui/show-coverage.stdout
@@ -1,7 +1,7 @@
 +-------------------------------------+------------+------------+------------+------------+
 | File                                | Documented | Percentage |   Examples | Percentage |
 +-------------------------------------+------------+------------+------------+------------+
-| ...ests/rustdoc-ui/show-coverage.rs |          1 |      50.0% |          1 |      50.0% |
+| ...ests/rustdoc-ui/show-coverage.rs |          1 |      50.0% |          1 |     100.0% |
 +-------------------------------------+------------+------------+------------+------------+
-| Total                               |          1 |      50.0% |          1 |      50.0% |
+| Total                               |          1 |      50.0% |          1 |     100.0% |
 +-------------------------------------+------------+------------+------------+------------+