diff --git a/src/doc/rustdoc/src/unstable-features.md b/src/doc/rustdoc/src/unstable-features.md index e9524c0b78d53..db8426492eec0 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 bf851b278b82a..c288a3cf2a475 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 92f58556975ae..070fed0783e76 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 8188740f8739b..793adeb351801 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 c2be73ce3edd7..25fd896baf1d3 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 391ba517077c7..058c5d6c468f3 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 acdb8128443fd..f1f36e8830d6d 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 86d7c83d33598..ccb241d4037e2 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 ebf2a2d54f75c..d230f1606935c 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 @@ -16,23 +10,11 @@ note: the lint level is defined here 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 40f35728d79b0..8e5c31d50edc7 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 f9331250154d7..22533b9816a74 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 @@ -10,12 +10,6 @@ note: the lint level is defined here 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 | @@ -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 ed5b5a60212eb..e6e882b2c57f8 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 b3b7679771f22..b9e0316545e77 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% | +-------------------------------------+------------+------------+------------+------------+