From a51b13042e48c40a87597496fac01dc605aca55d Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Thu, 12 Nov 2020 14:57:44 +0100 Subject: [PATCH 1/3] Add --check option to rustdoc --- src/librustdoc/config.rs | 6 ++++++ src/librustdoc/lib.rs | 5 +++++ 2 files changed, 11 insertions(+) diff --git a/src/librustdoc/config.rs b/src/librustdoc/config.rs index 02885f519363c..c248d57a9ddf4 100644 --- a/src/librustdoc/config.rs +++ b/src/librustdoc/config.rs @@ -145,6 +145,9 @@ pub struct Options { pub render_options: RenderOptions, /// Output format rendering (used only for "show-coverage" option for the moment) pub output_format: Option, + /// If this option is set to `true`, rustdoc will only run checks and not generate + /// documentation. + pub run_check: bool, } impl fmt::Debug for Options { @@ -185,6 +188,7 @@ impl fmt::Debug for Options { .field("runtool", &self.runtool) .field("runtool_args", &self.runtool_args) .field("enable-per-target-ignores", &self.enable_per_target_ignores) + .field("run_check", &self.run_check) .finish() } } @@ -581,6 +585,7 @@ impl Options { let enable_per_target_ignores = matches.opt_present("enable-per-target-ignores"); let document_private = matches.opt_present("document-private-items"); let document_hidden = matches.opt_present("document-hidden-items"); + let run_check = matches.opt_present("check"); let (lint_opts, describe_lints, lint_cap) = get_cmd_lint_options(matches, error_format); @@ -616,6 +621,7 @@ impl Options { runtool_args, enable_per_target_ignores, test_builder, + run_check, render_options: RenderOptions { output, external_html, diff --git a/src/librustdoc/lib.rs b/src/librustdoc/lib.rs index 7efbca5c6c3b7..d23c722e78edf 100644 --- a/src/librustdoc/lib.rs +++ b/src/librustdoc/lib.rs @@ -423,6 +423,7 @@ fn opts() -> Vec { "specified the rustc-like binary to use as the test builder", ) }), + unstable("check", |o| o.optflag("", "check", "Run rustdoc checks")), ] } @@ -514,6 +515,7 @@ fn main_options(options: config::Options) -> MainResult { // but we can't crates the Handler ahead of time because it's not Send let diag_opts = (options.error_format, options.edition, options.debugging_opts.clone()); let show_coverage = options.show_coverage; + let run_check = options.run_check; // First, parse the crate and extract all relevant information. info!("starting to run rustc"); @@ -539,6 +541,9 @@ fn main_options(options: config::Options) -> MainResult { // if we ran coverage, bail early, we don't need to also generate docs at this point // (also we didn't load in any of the useful passes) return Ok(()); + } else if run_check { + // Since we're in "check" mode, no need to generate anything beyond this point. + return Ok(()); } info!("going to format"); From 5e154fae925792096b11a6f6f30fc80f7362a6cf Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Thu, 12 Nov 2020 14:58:07 +0100 Subject: [PATCH 2/3] Add tests for rustdoc --check option --- src/test/rustdoc-ui/check-fail.rs | 10 ++++++ src/test/rustdoc-ui/check-fail.stderr | 49 +++++++++++++++++++++++++++ src/test/rustdoc-ui/check.rs | 11 ++++++ src/test/rustdoc-ui/check.stderr | 49 +++++++++++++++++++++++++++ src/test/rustdoc/check.rs | 5 +++ 5 files changed, 124 insertions(+) create mode 100644 src/test/rustdoc-ui/check-fail.rs create mode 100644 src/test/rustdoc-ui/check-fail.stderr create mode 100644 src/test/rustdoc-ui/check.rs create mode 100644 src/test/rustdoc-ui/check.stderr create mode 100644 src/test/rustdoc/check.rs diff --git a/src/test/rustdoc-ui/check-fail.rs b/src/test/rustdoc-ui/check-fail.rs new file mode 100644 index 0000000000000..ccc9d24c1595a --- /dev/null +++ b/src/test/rustdoc-ui/check-fail.rs @@ -0,0 +1,10 @@ +// compile-flags: -Z unstable-options --check + +#![deny(missing_docs)] +//~^ ERROR +//~^^ ERROR +#![deny(rustdoc)] + +pub fn foo() {} +//~^ ERROR +//~^^ ERROR diff --git a/src/test/rustdoc-ui/check-fail.stderr b/src/test/rustdoc-ui/check-fail.stderr new file mode 100644 index 0000000000000..979b2292f609b --- /dev/null +++ b/src/test/rustdoc-ui/check-fail.stderr @@ -0,0 +1,49 @@ +error: missing documentation for the crate + --> $DIR/check-fail.rs:3:1 + | +LL | / #![deny(missing_docs)] +LL | | +LL | | +LL | | #![deny(rustdoc)] +LL | | +LL | | pub fn foo() {} + | |_______________^ + | +note: the lint level is defined here + --> $DIR/check-fail.rs:3:9 + | +LL | #![deny(missing_docs)] + | ^^^^^^^^^^^^ + +error: missing documentation for a function + --> $DIR/check-fail.rs:8:1 + | +LL | pub fn foo() {} + | ^^^^^^^^^^^^ + +error: missing code example in this documentation + --> $DIR/check-fail.rs:3:1 + | +LL | / #![deny(missing_docs)] +LL | | +LL | | +LL | | #![deny(rustdoc)] +LL | | +LL | | pub fn foo() {} + | |_______________^ + | +note: the lint level is defined here + --> $DIR/check-fail.rs:6:9 + | +LL | #![deny(rustdoc)] + | ^^^^^^^ + = note: `#[deny(missing_doc_code_examples)]` implied by `#[deny(rustdoc)]` + +error: missing code example in this documentation + --> $DIR/check-fail.rs:8:1 + | +LL | pub fn foo() {} + | ^^^^^^^^^^^^^^^ + +error: aborting due to 4 previous errors + diff --git a/src/test/rustdoc-ui/check.rs b/src/test/rustdoc-ui/check.rs new file mode 100644 index 0000000000000..022c56214d451 --- /dev/null +++ b/src/test/rustdoc-ui/check.rs @@ -0,0 +1,11 @@ +// check-pass +// compile-flags: -Z unstable-options --check + +#![warn(missing_docs)] +//~^ WARN +//~^^ WARN +#![warn(rustdoc)] + +pub fn foo() {} +//~^ WARN +//~^^ WARN diff --git a/src/test/rustdoc-ui/check.stderr b/src/test/rustdoc-ui/check.stderr new file mode 100644 index 0000000000000..27e5a736148e1 --- /dev/null +++ b/src/test/rustdoc-ui/check.stderr @@ -0,0 +1,49 @@ +warning: missing documentation for the crate + --> $DIR/check.rs:4:1 + | +LL | / #![warn(missing_docs)] +LL | | +LL | | +LL | | #![warn(rustdoc)] +LL | | +LL | | pub fn foo() {} + | |_______________^ + | +note: the lint level is defined here + --> $DIR/check.rs:4:9 + | +LL | #![warn(missing_docs)] + | ^^^^^^^^^^^^ + +warning: missing documentation for a function + --> $DIR/check.rs:9:1 + | +LL | pub fn foo() {} + | ^^^^^^^^^^^^ + +warning: missing code example in this documentation + --> $DIR/check.rs:4:1 + | +LL | / #![warn(missing_docs)] +LL | | +LL | | +LL | | #![warn(rustdoc)] +LL | | +LL | | pub fn foo() {} + | |_______________^ + | +note: the lint level is defined here + --> $DIR/check.rs:7:9 + | +LL | #![warn(rustdoc)] + | ^^^^^^^ + = note: `#[warn(missing_doc_code_examples)]` implied by `#[warn(rustdoc)]` + +warning: missing code example in this documentation + --> $DIR/check.rs:9:1 + | +LL | pub fn foo() {} + | ^^^^^^^^^^^^^^^ + +warning: 4 warnings emitted + diff --git a/src/test/rustdoc/check.rs b/src/test/rustdoc/check.rs new file mode 100644 index 0000000000000..1fb4b35ddbe86 --- /dev/null +++ b/src/test/rustdoc/check.rs @@ -0,0 +1,5 @@ +// compile-flags: -Z unstable-options --check + +// @!has check/fn.foo.html +// @!has check/index.html +pub fn foo() {} From a06fd1f4f4b71b0571f2c1f35e981a1863638765 Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Thu, 12 Nov 2020 21:55:26 +0100 Subject: [PATCH 3/3] Ensure that INVALID_CODEBLOCK_ATTRIBUTES lint is emitted --- src/test/rustdoc-ui/check-fail.rs | 15 ++++++- src/test/rustdoc-ui/check-fail.stderr | 60 +++++++++++++++------------ 2 files changed, 47 insertions(+), 28 deletions(-) diff --git a/src/test/rustdoc-ui/check-fail.rs b/src/test/rustdoc-ui/check-fail.rs index ccc9d24c1595a..291fc112c3407 100644 --- a/src/test/rustdoc-ui/check-fail.rs +++ b/src/test/rustdoc-ui/check-fail.rs @@ -1,10 +1,21 @@ // compile-flags: -Z unstable-options --check #![deny(missing_docs)] -//~^ ERROR -//~^^ ERROR #![deny(rustdoc)] +//! ```rust,testharness +//~^ ERROR +//! let x = 12; +//! ``` + pub fn foo() {} //~^ ERROR //~^^ ERROR + +/// hello +//~^ ERROR +/// +/// ```rust,testharness +/// let x = 12; +/// ``` +pub fn bar() {} diff --git a/src/test/rustdoc-ui/check-fail.stderr b/src/test/rustdoc-ui/check-fail.stderr index 979b2292f609b..b4f255642da53 100644 --- a/src/test/rustdoc-ui/check-fail.stderr +++ b/src/test/rustdoc-ui/check-fail.stderr @@ -1,13 +1,8 @@ -error: missing documentation for the crate - --> $DIR/check-fail.rs:3:1 +error: missing documentation for a function + --> $DIR/check-fail.rs:11:1 | -LL | / #![deny(missing_docs)] -LL | | -LL | | -LL | | #![deny(rustdoc)] -LL | | -LL | | pub fn foo() {} - | |_______________^ +LL | pub fn foo() {} + | ^^^^^^^^^^^^ | note: the lint level is defined here --> $DIR/check-fail.rs:3:9 @@ -15,35 +10,48 @@ note: the lint level is defined here LL | #![deny(missing_docs)] | ^^^^^^^^^^^^ -error: missing documentation for a function - --> $DIR/check-fail.rs:8:1 +error: missing code example in this documentation + --> $DIR/check-fail.rs:11:1 | LL | pub fn foo() {} - | ^^^^^^^^^^^^ + | ^^^^^^^^^^^^^^^ + | +note: the lint level is defined here + --> $DIR/check-fail.rs:4:9 + | +LL | #![deny(rustdoc)] + | ^^^^^^^ + = note: `#[deny(missing_doc_code_examples)]` implied by `#[deny(rustdoc)]` -error: missing code example in this documentation - --> $DIR/check-fail.rs:3:1 +error: unknown attribute `testharness`. Did you mean `test_harness`? + --> $DIR/check-fail.rs:6:1 | -LL | / #![deny(missing_docs)] -LL | | -LL | | -LL | | #![deny(rustdoc)] +LL | / //! ```rust,testharness LL | | -LL | | pub fn foo() {} - | |_______________^ +LL | | //! let x = 12; +LL | | //! ``` + | |_______^ | note: the lint level is defined here - --> $DIR/check-fail.rs:6:9 + --> $DIR/check-fail.rs:4:9 | LL | #![deny(rustdoc)] | ^^^^^^^ - = note: `#[deny(missing_doc_code_examples)]` implied by `#[deny(rustdoc)]` + = note: `#[deny(invalid_codeblock_attributes)]` implied by `#[deny(rustdoc)]` + = 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: missing code example in this documentation - --> $DIR/check-fail.rs:8:1 +error: unknown attribute `testharness`. Did you mean `test_harness`? + --> $DIR/check-fail.rs:15:1 | -LL | pub fn foo() {} - | ^^^^^^^^^^^^^^^ +LL | / /// hello +LL | | +LL | | /// +LL | | /// ```rust,testharness +LL | | /// let x = 12; +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 error: aborting due to 4 previous errors