bjoernager/rust
bjoernager/rust
1
Fork 0
Code Activity

Feature gate the rustdoc::missing_doc_code_examples lint

Browse source
This commit is contained in:
Wim Looman 2022-09-12 20:10:35 +02:00
parent fd1a399c4f
commit 72cf46aa72
No known key found for this signature in database
GPG key ID: C6F5748C6DD1607B
16 changed files with 93 additions and 37 deletions
Download patch file Download diff file Expand all files Collapse all files

2
compiler/rustc_feature/src/active.rs
View file

@ -221,6 +221,8 @@ declare_features! (
(active, rustc_private, "1.0.0", Some(27812), None), (active, rustc_private, "1.0.0", Some(27812), None),
/// Allows using internal rustdoc features like `doc(primitive)` or `doc(keyword)`. /// Allows using internal rustdoc features like `doc(primitive)` or `doc(keyword)`.
(active, rustdoc_internals, "1.58.0", Some(90418), None), (active, rustdoc_internals, "1.58.0", Some(90418), None),
/// Allows using the `rustdoc::missing_doc_code_examples` lint
(active, rustdoc_missing_doc_code_examples, "1.31.0", Some(101730), None),
/// Allows using `#[start]` on a function indicating that it is the program entrypoint. /// Allows using `#[start]` on a function indicating that it is the program entrypoint.
(active, start, "1.0.0", Some(29633), None), (active, start, "1.0.0", Some(29633), None),
/// Allows using `#[structural_match]` which indicates that a type is structurally matchable. /// Allows using `#[structural_match]` which indicates that a type is structurally matchable.

1
compiler/rustc_span/src/symbol.rs
View file

@ -1292,6 +1292,7 @@ symbols! {
rustc_variance, rustc_variance,
rustdoc, rustdoc,
rustdoc_internals, rustdoc_internals,
rustdoc_missing_doc_code_examples,
rustfmt, rustfmt,
rvalue_static_promotion, rvalue_static_promotion,
s, s,

9
src/librustdoc/lint.rs
View file

@ -64,9 +64,13 @@ where
} }
macro_rules! declare_rustdoc_lint { macro_rules! declare_rustdoc_lint {
($(#[$attr:meta])* $name: ident, $level: ident, $descr: literal $(,)?) => { (
$(#[$attr:meta])* $name: ident, $level: ident, $descr: literal $(,)?
$(@feature_gate = $gate:expr;)?
) => {
declare_tool_lint! { declare_tool_lint! {
$(#[$attr])* pub rustdoc::$name, $level, $descr $(#[$attr])* pub rustdoc::$name, $level, $descr
$(, @feature_gate = $gate;)?
} }
} }
} }
@ -123,7 +127,8 @@ declare_rustdoc_lint! {
/// [rustdoc book]: ../../../rustdoc/lints.html#missing_doc_code_examples /// [rustdoc book]: ../../../rustdoc/lints.html#missing_doc_code_examples
MISSING_DOC_CODE_EXAMPLES, MISSING_DOC_CODE_EXAMPLES,
Allow, Allow,
"detects publicly-exported items without code samples in their documentation" "detects publicly-exported items without code samples in their documentation",
@feature_gate = rustc_span::symbol::sym::rustdoc_missing_doc_code_examples;
} }
declare_rustdoc_lint! { declare_rustdoc_lint! {

2
src/librustdoc/passes/check_doc_test_visibility.rs
View file

@ -117,7 +117,7 @@ pub(crate) fn look_for_tests<'tcx>(cx: &DocContext<'tcx>, dox: &str, item: &Item
find_testable_code(dox, &mut tests, ErrorCodes::No, false, None); find_testable_code(dox, &mut tests, ErrorCodes::No, false, None);
if tests.found_tests == 0 && cx.tcx.sess.is_nightly_build() { if tests.found_tests == 0 && cx.tcx.features().rustdoc_missing_doc_code_examples {
if should_have_doc_example(cx, item) { if should_have_doc_example(cx, item) {
debug!("reporting error for {:?} (hir_id={:?})", item, hir_id); debug!("reporting error for {:?} (hir_id={:?})", item, hir_id);
let sp = item.attr_span(cx.tcx); let sp = item.attr_span(cx.tcx);

1
src/test/rustdoc-ui/check-fail.rs
View file

@ -1,5 +1,6 @@
// compile-flags: -Z unstable-options --check // compile-flags: -Z unstable-options --check
#![feature(rustdoc_missing_doc_code_examples)]
#![deny(missing_docs)] #![deny(missing_docs)]
#![deny(rustdoc::all)] #![deny(rustdoc::all)]

12
src/test/rustdoc-ui/check-fail.stderr
View file

@ -1,30 +1,30 @@
error: missing documentation for a function error: missing documentation for a function
--> $DIR/check-fail.rs:11:1 --> $DIR/check-fail.rs:12:1
| |
LL | pub fn foo() {} LL | pub fn foo() {}
| ^^^^^^^^^^^^ | ^^^^^^^^^^^^
| |
note: the lint level is defined here note: the lint level is defined here
--> $DIR/check-fail.rs:3:9 --> $DIR/check-fail.rs:4:9
| |
LL | #![deny(missing_docs)] LL | #![deny(missing_docs)]
| ^^^^^^^^^^^^ | ^^^^^^^^^^^^
error: missing code example in this documentation error: missing code example in this documentation
--> $DIR/check-fail.rs:11:1 --> $DIR/check-fail.rs:12:1
| |
LL | pub fn foo() {} LL | pub fn foo() {}
| ^^^^^^^^^^^^^^^ | ^^^^^^^^^^^^^^^
| |
note: the lint level is defined here note: the lint level is defined here
--> $DIR/check-fail.rs:4:9 --> $DIR/check-fail.rs:5:9
| |
LL | #![deny(rustdoc::all)] LL | #![deny(rustdoc::all)]
| ^^^^^^^^^^^^ | ^^^^^^^^^^^^
= note: `#[deny(rustdoc::missing_doc_code_examples)]` implied by `#[deny(rustdoc::all)]` = note: `#[deny(rustdoc::missing_doc_code_examples)]` implied by `#[deny(rustdoc::all)]`
error: unknown attribute `testharness`. Did you mean `test_harness`? error: unknown attribute `testharness`. Did you mean `test_harness`?
--> $DIR/check-fail.rs:6:1 --> $DIR/check-fail.rs:7:1
| |
LL | / //! ```rust,testharness LL | / //! ```rust,testharness
LL | | LL | |
@ -36,7 +36,7 @@ LL | | //! ```
= help: the code block will either not be tested if not marked as a rust one or the code will be wrapped inside a main function = help: the code block will either not be tested if not marked as a rust one or the code will be wrapped inside a main function
error: unknown attribute `testharness`. Did you mean `test_harness`? error: unknown attribute `testharness`. Did you mean `test_harness`?
--> $DIR/check-fail.rs:15:1 --> $DIR/check-fail.rs:16:1
| |
LL | / /// hello LL | / /// hello
LL | | LL | |

4
src/test/rustdoc-ui/check.rs
View file

@ -2,9 +2,11 @@
// compile-flags: -Z unstable-options --check // compile-flags: -Z unstable-options --check
// normalize-stderr-test: "nightly|beta|1\.[0-9][0-9]\.[0-9]" -> "$$CHANNEL" // normalize-stderr-test: "nightly|beta|1\.[0-9][0-9]\.[0-9]" -> "$$CHANNEL"
#![warn(missing_docs)] #![feature(rustdoc_missing_doc_code_examples)]
//~^ WARN //~^ WARN
//~^^ WARN //~^^ WARN
#![warn(missing_docs)]
#![warn(rustdoc::all)] #![warn(rustdoc::all)]
pub fn foo() {} pub fn foo() {}

18
src/test/rustdoc-ui/check.stderr
View file

@ -1,22 +1,23 @@
warning: missing documentation for the crate warning: missing documentation for the crate
--> $DIR/check.rs:5:1 --> $DIR/check.rs:5:1
| |
LL | / #![warn(missing_docs)] LL | / #![feature(rustdoc_missing_doc_code_examples)]
LL | | LL | |
LL | | LL | |
LL | | #![warn(rustdoc::all)] LL | |
... |
LL | | LL | |
LL | | pub fn foo() {} LL | | pub fn foo() {}
| |_______________^ | |_______________^
| |
note: the lint level is defined here note: the lint level is defined here
--> $DIR/check.rs:5:9 --> $DIR/check.rs:9:9
| |
LL | #![warn(missing_docs)] LL | #![warn(missing_docs)]
| ^^^^^^^^^^^^ | ^^^^^^^^^^^^
warning: missing documentation for a function warning: missing documentation for a function
--> $DIR/check.rs:10:1 --> $DIR/check.rs:12:1
| |
LL | pub fn foo() {} LL | pub fn foo() {}
| ^^^^^^^^^^^^ | ^^^^^^^^^^^^
@ -24,7 +25,7 @@ LL | pub fn foo() {}
warning: no documentation found for this crate's top-level module warning: no documentation found for this crate's top-level module
| |
note: the lint level is defined here note: the lint level is defined here
--> $DIR/check.rs:8:9 --> $DIR/check.rs:10:9
| |
LL | #![warn(rustdoc::all)] LL | #![warn(rustdoc::all)]
| ^^^^^^^^^^^^ | ^^^^^^^^^^^^
@ -35,10 +36,11 @@ LL | #![warn(rustdoc::all)]
warning: missing code example in this documentation warning: missing code example in this documentation
--> $DIR/check.rs:5:1 --> $DIR/check.rs:5:1
| |
LL | / #![warn(missing_docs)] LL | / #![feature(rustdoc_missing_doc_code_examples)]
LL | | LL | |
LL | | LL | |
LL | | #![warn(rustdoc::all)] LL | |
... |
LL | | LL | |
LL | | pub fn foo() {} LL | | pub fn foo() {}
| |_______________^ | |_______________^
@ -46,7 +48,7 @@ LL | | pub fn foo() {}
= note: `#[warn(rustdoc::missing_doc_code_examples)]` implied by `#[warn(rustdoc::all)]` = note: `#[warn(rustdoc::missing_doc_code_examples)]` implied by `#[warn(rustdoc::all)]`
warning: missing code example in this documentation warning: missing code example in this documentation
--> $DIR/check.rs:10:1 --> $DIR/check.rs:12:1
| |
LL | pub fn foo() {} LL | pub fn foo() {}
| ^^^^^^^^^^^^^^^ | ^^^^^^^^^^^^^^^

3
src/test/rustdoc-ui/doc-without-codeblock.rs
View file

@ -1,4 +1,5 @@
#![deny(rustdoc::missing_doc_code_examples)] //~ ERROR missing code example in this documentation #![feature(rustdoc_missing_doc_code_examples)] //~ ERROR missing code example in this documentation
#![deny(rustdoc::missing_doc_code_examples)]
/// Some docs. /// Some docs.
//~^ ERROR missing code example in this documentation //~^ ERROR missing code example in this documentation

12
src/test/rustdoc-ui/doc-without-codeblock.stderr
View file

@ -1,35 +1,35 @@
error: missing code example in this documentation error: missing code example in this documentation
--> $DIR/doc-without-codeblock.rs:1:1 --> $DIR/doc-without-codeblock.rs:1:1
| |
LL | / #![deny(rustdoc::missing_doc_code_examples)] LL | / #![feature(rustdoc_missing_doc_code_examples)]
LL | | #![deny(rustdoc::missing_doc_code_examples)]
LL | | LL | |
LL | | /// Some docs. LL | | /// Some docs.
LL | |
... | ... |
LL | | } LL | | }
LL | | } LL | | }
| |_^ | |_^
| |
note: the lint level is defined here note: the lint level is defined here
--> $DIR/doc-without-codeblock.rs:1:9 --> $DIR/doc-without-codeblock.rs:2:9
| |
LL | #![deny(rustdoc::missing_doc_code_examples)] LL | #![deny(rustdoc::missing_doc_code_examples)]
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
error: missing code example in this documentation error: missing code example in this documentation
--> $DIR/doc-without-codeblock.rs:7:1 --> $DIR/doc-without-codeblock.rs:8:1
| |
LL | /// And then, the princess died. LL | /// And then, the princess died.
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
error: missing code example in this documentation error: missing code example in this documentation
--> $DIR/doc-without-codeblock.rs:10:5 --> $DIR/doc-without-codeblock.rs:11:5
| |
LL | /// Or maybe not because she saved herself! LL | /// Or maybe not because she saved herself!
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
error: missing code example in this documentation error: missing code example in this documentation
--> $DIR/doc-without-codeblock.rs:3:1 --> $DIR/doc-without-codeblock.rs:4:1
| |
LL | /// Some docs. LL | /// Some docs.
| ^^^^^^^^^^^^^^ | ^^^^^^^^^^^^^^

10
src/test/rustdoc-ui/feature-gate-rustdoc_missing_doc_code_examples.rs Normal file
View file

@ -0,0 +1,10 @@
#![deny(unknown_lints)]
//~^ NOTE defined here
#![allow(rustdoc::missing_doc_code_examples)]
//~^ ERROR unknown lint
//~| ERROR unknown lint
//~| NOTE lint is unstable
//~| NOTE lint is unstable
//~| NOTE see issue
//~| NOTE see issue

29
src/test/rustdoc-ui/feature-gate-rustdoc_missing_doc_code_examples.stderr Normal file
View file

@ -0,0 +1,29 @@
error: unknown lint: `rustdoc::missing_doc_code_examples`
--> $DIR/feature-gate-rustdoc_missing_doc_code_examples.rs:4:1
|
LL | #![allow(rustdoc::missing_doc_code_examples)]
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
note: the lint level is defined here
--> $DIR/feature-gate-rustdoc_missing_doc_code_examples.rs:1:9
|
LL | #![deny(unknown_lints)]
| ^^^^^^^^^^^^^
= note: the `rustdoc::missing_doc_code_examples` lint is unstable
= note: see issue #101730 <https://github.com/rust-lang/rust/issues/101730> for more information
= help: add `#![feature(rustdoc_missing_doc_code_examples)]` to the crate attributes to enable
error: unknown lint: `rustdoc::missing_doc_code_examples`
--> $DIR/feature-gate-rustdoc_missing_doc_code_examples.rs:4:1
|
LL | #![allow(rustdoc::missing_doc_code_examples)]
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
= note: the `rustdoc::missing_doc_code_examples` lint is unstable
= note: see issue #101730 <https://github.com/rust-lang/rust/issues/101730> for more information
= help: add `#![feature(rustdoc_missing_doc_code_examples)]` to the crate attributes to enable
error: Compilation failed, aborting rustdoc
error: aborting due to 3 previous errors

2
src/test/rustdoc-ui/lint-group.rs
View file

@ -1,3 +1,5 @@
#![feature(rustdoc_missing_doc_code_examples)]
//! Documenting the kinds of lints emitted by rustdoc. //! Documenting the kinds of lints emitted by rustdoc.
//! //!
//! ``` //! ```

12
src/test/rustdoc-ui/lint-group.stderr
View file

@ -1,18 +1,18 @@
error: missing code example in this documentation error: missing code example in this documentation
--> $DIR/lint-group.rs:16:1 --> $DIR/lint-group.rs:18:1
| |
LL | /// wait, this doesn't have a doctest? LL | /// wait, this doesn't have a doctest?
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
| |
note: the lint level is defined here note: the lint level is defined here
--> $DIR/lint-group.rs:7:9 --> $DIR/lint-group.rs:9:9
| |
LL | #![deny(rustdoc::all)] LL | #![deny(rustdoc::all)]
| ^^^^^^^^^^^^ | ^^^^^^^^^^^^
= note: `#[deny(rustdoc::missing_doc_code_examples)]` implied by `#[deny(rustdoc::all)]` = note: `#[deny(rustdoc::missing_doc_code_examples)]` implied by `#[deny(rustdoc::all)]`
error: documentation test in private item error: documentation test in private item
--> $DIR/lint-group.rs:19:1 --> $DIR/lint-group.rs:21:1
| |
LL | / /// wait, this *does* have a doctest? LL | / /// wait, this *does* have a doctest?
LL | | /// LL | | ///
@ -24,13 +24,13 @@ LL | | /// ```
= note: `#[deny(rustdoc::private_doc_tests)]` implied by `#[deny(rustdoc::all)]` = note: `#[deny(rustdoc::private_doc_tests)]` implied by `#[deny(rustdoc::all)]`
error: missing code example in this documentation error: missing code example in this documentation
--> $DIR/lint-group.rs:26:1 --> $DIR/lint-group.rs:28:1
| |
LL | /// <unknown> LL | /// <unknown>
| ^^^^^^^^^^^^^ | ^^^^^^^^^^^^^
error: unresolved link to `error` error: unresolved link to `error`
--> $DIR/lint-group.rs:9:29 --> $DIR/lint-group.rs:11:29
| |
LL | /// what up, let's make an [error] LL | /// what up, let's make an [error]
| ^^^^^ no item named `error` in scope | ^^^^^ no item named `error` in scope
@ -39,7 +39,7 @@ LL | /// what up, let's make an [error]
= help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]` = help: to escape `[` and `]` characters, add '\' before them like `\[` or `\]`
error: unclosed HTML tag `unknown` error: unclosed HTML tag `unknown`
--> $DIR/lint-group.rs:26:5 --> $DIR/lint-group.rs:28:5
| |
LL | /// <unknown> LL | /// <unknown>
| ^^^^^^^^^ | ^^^^^^^^^

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

@ -1,3 +1,4 @@
#![feature(rustdoc_missing_doc_code_examples)]
#![deny(missing_docs)] #![deny(missing_docs)]
#![deny(rustdoc::missing_doc_code_examples)] #![deny(rustdoc::missing_doc_code_examples)]

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

@ -1,35 +1,35 @@
error: missing code example in this documentation error: missing code example in this documentation
--> $DIR/lint-missing-doc-code-example.rs:19:1 --> $DIR/lint-missing-doc-code-example.rs:20:1
| |
LL | pub mod module1 { LL | pub mod module1 {
| ^^^^^^^^^^^^^^^ | ^^^^^^^^^^^^^^^
| |
note: the lint level is defined here note: the lint level is defined here
--> $DIR/lint-missing-doc-code-example.rs:2:9 --> $DIR/lint-missing-doc-code-example.rs:3:9
| |
LL | #![deny(rustdoc::missing_doc_code_examples)] LL | #![deny(rustdoc::missing_doc_code_examples)]
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
error: missing code example in this documentation error: missing code example in this documentation
--> $DIR/lint-missing-doc-code-example.rs:37:3 --> $DIR/lint-missing-doc-code-example.rs:38:3
| |
LL | /// doc LL | /// doc
| ^^^^^^^ | ^^^^^^^
error: missing code example in this documentation error: missing code example in this documentation
--> $DIR/lint-missing-doc-code-example.rs:49:1 --> $DIR/lint-missing-doc-code-example.rs:50:1
| |
LL | /// Doc LL | /// Doc
| ^^^^^^^ | ^^^^^^^
error: missing code example in this documentation error: missing code example in this documentation
--> $DIR/lint-missing-doc-code-example.rs:56:1 --> $DIR/lint-missing-doc-code-example.rs:57:1
| |
LL | /// Doc LL | /// Doc
| ^^^^^^^ | ^^^^^^^
error: missing code example in this documentation error: missing code example in this documentation
--> $DIR/lint-missing-doc-code-example.rs:63:1 --> $DIR/lint-missing-doc-code-example.rs:64:1
| |
LL | /// Doc LL | /// Doc
| ^^^^^^^ | ^^^^^^^