From 12607ef569dfa086d5475d0d7b1858965931519b Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Sun, 1 Dec 2019 20:12:49 +0100 Subject: [PATCH 1/6] Add lint when no doc is present at the crate-level --- src/librustc_session/lint/builtin.rs | 7 +++++++ src/librustdoc/core.rs | 19 +++++++++++++++++++ .../rustdoc-ui/no-crate-level-doc-lint.rs | 3 +++ .../rustdoc-ui/no-crate-level-doc-lint.stderr | 13 +++++++++++++ 4 files changed, 42 insertions(+) create mode 100644 src/test/rustdoc-ui/no-crate-level-doc-lint.rs create mode 100644 src/test/rustdoc-ui/no-crate-level-doc-lint.stderr diff --git a/src/librustc_session/lint/builtin.rs b/src/librustc_session/lint/builtin.rs index f8a4e024605aa..deb119ccb9730 100644 --- a/src/librustc_session/lint/builtin.rs +++ b/src/librustc_session/lint/builtin.rs @@ -386,6 +386,12 @@ declare_lint! { "failures in resolving intra-doc link targets" } +declare_lint! { + pub NO_CRATE_LEVEL_DOC, + Allow, + "detects crates with no crate-level documentation" +} + declare_lint! { pub MISSING_DOC_CODE_EXAMPLES, Allow, @@ -547,6 +553,7 @@ declare_lint_pass! { UNSTABLE_NAME_COLLISIONS, IRREFUTABLE_LET_PATTERNS, INTRA_DOC_LINK_RESOLUTION_FAILURE, + NO_CRATE_LEVEL_DOC, MISSING_DOC_CODE_EXAMPLES, PRIVATE_DOC_TESTS, WHERE_CLAUSES_OBJECT_SAFETY, diff --git a/src/librustdoc/core.rs b/src/librustdoc/core.rs index f0b9ad2852f51..a45761ba4a8b2 100644 --- a/src/librustdoc/core.rs +++ b/src/librustdoc/core.rs @@ -249,6 +249,7 @@ pub fn run_core(options: RustdocOptions) -> (clean::Crate, RenderInfo, RenderOpt let missing_docs = rustc_lint::builtin::MISSING_DOCS.name; let missing_doc_example = rustc_lint::builtin::MISSING_DOC_CODE_EXAMPLES.name; let private_doc_tests = rustc_lint::builtin::PRIVATE_DOC_TESTS.name; + let no_crate_level_doc = rustc_lint::builtin::NO_CRATE_LEVEL_DOC.name; // In addition to those specific lints, we also need to whitelist those given through // command line, otherwise they'll get ignored and we don't want that. @@ -258,6 +259,7 @@ pub fn run_core(options: RustdocOptions) -> (clean::Crate, RenderInfo, RenderOpt missing_docs.to_owned(), missing_doc_example.to_owned(), private_doc_tests.to_owned(), + no_crate_level_doc.to_owned(), ]; whitelisted_lints.extend(lint_opts.iter().map(|(lint, _)| lint).cloned()); @@ -411,6 +413,23 @@ pub fn run_core(options: RustdocOptions) -> (clean::Crate, RenderInfo, RenderOpt let mut krate = clean::krate(&mut ctxt); + if let Some(ref m) = krate.module { + match m.doc_value() { + None | Some("") => { + let mut diag = tcx.struct_lint_node( + rustc_lint::builtin::NO_CRATE_LEVEL_DOC, + ctxt.as_local_hir_id(m.def_id).unwrap(), + "No documentation found on this crate top module.\n\n\ + Maybe you could be interested into looking at this documentation:\n\ + https://doc.rust-lang.org/nightly/rustdoc/how-to-write-documentation\ + .html" + ); + diag.emit(); + } + _ => {} + } + } + fn report_deprecated_attr(name: &str, diag: &rustc_errors::Handler) { let mut msg = diag.struct_warn(&format!( "the `#![doc({})]` attribute is \ diff --git a/src/test/rustdoc-ui/no-crate-level-doc-lint.rs b/src/test/rustdoc-ui/no-crate-level-doc-lint.rs new file mode 100644 index 0000000000000..e939f3a44d3ff --- /dev/null +++ b/src/test/rustdoc-ui/no-crate-level-doc-lint.rs @@ -0,0 +1,3 @@ +#![deny(no_crate_level_doc)] + +pub fn foo() {} diff --git a/src/test/rustdoc-ui/no-crate-level-doc-lint.stderr b/src/test/rustdoc-ui/no-crate-level-doc-lint.stderr new file mode 100644 index 0000000000000..45c2493686883 --- /dev/null +++ b/src/test/rustdoc-ui/no-crate-level-doc-lint.stderr @@ -0,0 +1,13 @@ +error: No documentation found on this crate top module. + +Maybe you could be interested into looking at this documentation: +https://doc.rust-lang.org/nightly/rustdoc/how-to-write-documentation.html + | +note: lint level defined here + --> $DIR/no-crate-level-doc-lint.rs:1:9 + | +LL | #![deny(no_crate_level_doc)] + | ^^^^^^^^^^^^^^^^^^ + +error: aborting due to previous error + From f767f541e7a7eed4cd827511146372021acacc22 Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Tue, 11 Feb 2020 11:45:40 +0100 Subject: [PATCH 2/6] rename NO_CRATE_LEVEL_DOC lint into MISSING_CRATE_LEVEL_DOC --- src/librustc_session/lint/builtin.rs | 4 ++-- src/librustdoc/core.rs | 7 +++---- 2 files changed, 5 insertions(+), 6 deletions(-) diff --git a/src/librustc_session/lint/builtin.rs b/src/librustc_session/lint/builtin.rs index deb119ccb9730..1c010139ef6db 100644 --- a/src/librustc_session/lint/builtin.rs +++ b/src/librustc_session/lint/builtin.rs @@ -387,7 +387,7 @@ declare_lint! { } declare_lint! { - pub NO_CRATE_LEVEL_DOC, + pub MISSING_CRATE_LEVEL_DOC, Allow, "detects crates with no crate-level documentation" } @@ -553,7 +553,7 @@ declare_lint_pass! { UNSTABLE_NAME_COLLISIONS, IRREFUTABLE_LET_PATTERNS, INTRA_DOC_LINK_RESOLUTION_FAILURE, - NO_CRATE_LEVEL_DOC, + MISSING_CRATE_LEVEL_DOC, MISSING_DOC_CODE_EXAMPLES, PRIVATE_DOC_TESTS, WHERE_CLAUSES_OBJECT_SAFETY, diff --git a/src/librustdoc/core.rs b/src/librustdoc/core.rs index a45761ba4a8b2..47b6699368ccf 100644 --- a/src/librustdoc/core.rs +++ b/src/librustdoc/core.rs @@ -249,7 +249,7 @@ pub fn run_core(options: RustdocOptions) -> (clean::Crate, RenderInfo, RenderOpt let missing_docs = rustc_lint::builtin::MISSING_DOCS.name; let missing_doc_example = rustc_lint::builtin::MISSING_DOC_CODE_EXAMPLES.name; let private_doc_tests = rustc_lint::builtin::PRIVATE_DOC_TESTS.name; - let no_crate_level_doc = rustc_lint::builtin::NO_CRATE_LEVEL_DOC.name; + let no_crate_level_doc = rustc_lint::builtin::MISSING_CRATE_LEVEL_DOC.name; // In addition to those specific lints, we also need to whitelist those given through // command line, otherwise they'll get ignored and we don't want that. @@ -417,7 +417,7 @@ pub fn run_core(options: RustdocOptions) -> (clean::Crate, RenderInfo, RenderOpt match m.doc_value() { None | Some("") => { let mut diag = tcx.struct_lint_node( - rustc_lint::builtin::NO_CRATE_LEVEL_DOC, + rustc_lint::builtin::MISSING_CRATE_LEVEL_DOC, ctxt.as_local_hir_id(m.def_id).unwrap(), "No documentation found on this crate top module.\n\n\ Maybe you could be interested into looking at this documentation:\n\ @@ -432,8 +432,7 @@ pub fn run_core(options: RustdocOptions) -> (clean::Crate, RenderInfo, RenderOpt fn report_deprecated_attr(name: &str, diag: &rustc_errors::Handler) { let mut msg = diag.struct_warn(&format!( - "the `#![doc({})]` attribute is \ - considered deprecated", + "the `#![doc({})]` attribute is considered deprecated", name )); msg.warn( From a8b0e404875c1e08b330ddea1a2b9a520c193097 Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Tue, 11 Feb 2020 13:16:38 +0100 Subject: [PATCH 3/6] Improve code readability --- src/librustdoc/core.rs | 25 ++++++++++++------------- 1 file changed, 12 insertions(+), 13 deletions(-) diff --git a/src/librustdoc/core.rs b/src/librustdoc/core.rs index 47b6699368ccf..116bb70dcf62f 100644 --- a/src/librustdoc/core.rs +++ b/src/librustdoc/core.rs @@ -414,19 +414,18 @@ pub fn run_core(options: RustdocOptions) -> (clean::Crate, RenderInfo, RenderOpt let mut krate = clean::krate(&mut ctxt); if let Some(ref m) = krate.module { - match m.doc_value() { - None | Some("") => { - let mut diag = tcx.struct_lint_node( - rustc_lint::builtin::MISSING_CRATE_LEVEL_DOC, - ctxt.as_local_hir_id(m.def_id).unwrap(), - "No documentation found on this crate top module.\n\n\ - Maybe you could be interested into looking at this documentation:\n\ - https://doc.rust-lang.org/nightly/rustdoc/how-to-write-documentation\ - .html" - ); - diag.emit(); - } - _ => {} + if let None | Some("") = m.doc_value() { + let mut diag = tcx.struct_lint_node( + rustc_lint::builtin::MISSING_CRATE_LEVEL_DOC, + ctxt.as_local_hir_id(m.def_id).unwrap(), + "no documentation found for this crate's top-level module", + ); + diag.help( + "The following guide may be of use:\n\ + https://doc.rust-lang.org/nightly/rustdoc/how-to-write-documentation\ + .html", + ); + diag.emit(); } } From ffe1289fd249d31cd98b2da168281ba860330987 Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Tue, 11 Feb 2020 13:16:46 +0100 Subject: [PATCH 4/6] Update tests --- src/test/rustdoc-ui/no-crate-level-doc-lint.rs | 2 +- src/test/rustdoc-ui/no-crate-level-doc-lint.stderr | 13 ++++++------- 2 files changed, 7 insertions(+), 8 deletions(-) diff --git a/src/test/rustdoc-ui/no-crate-level-doc-lint.rs b/src/test/rustdoc-ui/no-crate-level-doc-lint.rs index e939f3a44d3ff..c65af73ead1e5 100644 --- a/src/test/rustdoc-ui/no-crate-level-doc-lint.rs +++ b/src/test/rustdoc-ui/no-crate-level-doc-lint.rs @@ -1,3 +1,3 @@ -#![deny(no_crate_level_doc)] +#![deny(missing_crate_level_doc)] pub fn foo() {} diff --git a/src/test/rustdoc-ui/no-crate-level-doc-lint.stderr b/src/test/rustdoc-ui/no-crate-level-doc-lint.stderr index 45c2493686883..f8d3723e7b0b4 100644 --- a/src/test/rustdoc-ui/no-crate-level-doc-lint.stderr +++ b/src/test/rustdoc-ui/no-crate-level-doc-lint.stderr @@ -1,13 +1,12 @@ -error: No documentation found on this crate top module. - -Maybe you could be interested into looking at this documentation: -https://doc.rust-lang.org/nightly/rustdoc/how-to-write-documentation.html +error: no documentation found for this crate's top-level module | -note: lint level defined here +note: the lint level is defined here --> $DIR/no-crate-level-doc-lint.rs:1:9 | -LL | #![deny(no_crate_level_doc)] - | ^^^^^^^^^^^^^^^^^^ +LL | #![deny(missing_crate_level_doc)] + | ^^^^^^^^^^^^^^^^^^^^^^^ + = help: The following guide may be of use: + https://doc.rust-lang.org/nightly/rustdoc/how-to-write-documentation.html error: aborting due to previous error From 966400253b3c5df2ed96e443d64147244dc6f338 Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Wed, 12 Feb 2020 15:48:08 +0100 Subject: [PATCH 5/6] Update to new diagnostic --- src/librustdoc/core.rs | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/src/librustdoc/core.rs b/src/librustdoc/core.rs index 116bb70dcf62f..4d2d81e48fc9e 100644 --- a/src/librustdoc/core.rs +++ b/src/librustdoc/core.rs @@ -415,17 +415,20 @@ pub fn run_core(options: RustdocOptions) -> (clean::Crate, RenderInfo, RenderOpt if let Some(ref m) = krate.module { if let None | Some("") = m.doc_value() { - let mut diag = tcx.struct_lint_node( + let help = "The following guide may be of use:\n\ + https://doc.rust-lang.org/nightly/rustdoc/how-to-write-documentation\ + .html"; + tcx.struct_lint_node( rustc_lint::builtin::MISSING_CRATE_LEVEL_DOC, ctxt.as_local_hir_id(m.def_id).unwrap(), - "no documentation found for this crate's top-level module", - ); - diag.help( - "The following guide may be of use:\n\ - https://doc.rust-lang.org/nightly/rustdoc/how-to-write-documentation\ - .html", + |lint| { + let mut diag = lint.build( + "no documentation found for this crate's top-level module", + ); + diag.help(help); + diag.emit(); + }, ); - diag.emit(); } } From be97eb4ece63b9e8e094939eb724885fcc2a6919 Mon Sep 17 00:00:00 2001 From: Guillaume Gomez Date: Sun, 22 Mar 2020 13:04:23 +0100 Subject: [PATCH 6/6] Update lint name to follow convention --- src/librustc_session/lint/builtin.rs | 4 ++-- src/librustdoc/core.rs | 6 +++--- src/test/rustdoc-ui/no-crate-level-doc-lint.rs | 2 +- src/test/rustdoc-ui/no-crate-level-doc-lint.stderr | 4 ++-- 4 files changed, 8 insertions(+), 8 deletions(-) diff --git a/src/librustc_session/lint/builtin.rs b/src/librustc_session/lint/builtin.rs index 1c010139ef6db..9ad6e792c28ba 100644 --- a/src/librustc_session/lint/builtin.rs +++ b/src/librustc_session/lint/builtin.rs @@ -387,7 +387,7 @@ declare_lint! { } declare_lint! { - pub MISSING_CRATE_LEVEL_DOC, + pub MISSING_CRATE_LEVEL_DOCS, Allow, "detects crates with no crate-level documentation" } @@ -553,7 +553,7 @@ declare_lint_pass! { UNSTABLE_NAME_COLLISIONS, IRREFUTABLE_LET_PATTERNS, INTRA_DOC_LINK_RESOLUTION_FAILURE, - MISSING_CRATE_LEVEL_DOC, + MISSING_CRATE_LEVEL_DOCS, MISSING_DOC_CODE_EXAMPLES, PRIVATE_DOC_TESTS, WHERE_CLAUSES_OBJECT_SAFETY, diff --git a/src/librustdoc/core.rs b/src/librustdoc/core.rs index 4d2d81e48fc9e..fe3a9b6b3dcdd 100644 --- a/src/librustdoc/core.rs +++ b/src/librustdoc/core.rs @@ -249,7 +249,7 @@ pub fn run_core(options: RustdocOptions) -> (clean::Crate, RenderInfo, RenderOpt let missing_docs = rustc_lint::builtin::MISSING_DOCS.name; let missing_doc_example = rustc_lint::builtin::MISSING_DOC_CODE_EXAMPLES.name; let private_doc_tests = rustc_lint::builtin::PRIVATE_DOC_TESTS.name; - let no_crate_level_doc = rustc_lint::builtin::MISSING_CRATE_LEVEL_DOC.name; + let no_crate_level_docs = rustc_lint::builtin::MISSING_CRATE_LEVEL_DOCS.name; // In addition to those specific lints, we also need to whitelist those given through // command line, otherwise they'll get ignored and we don't want that. @@ -259,7 +259,7 @@ pub fn run_core(options: RustdocOptions) -> (clean::Crate, RenderInfo, RenderOpt missing_docs.to_owned(), missing_doc_example.to_owned(), private_doc_tests.to_owned(), - no_crate_level_doc.to_owned(), + no_crate_level_docs.to_owned(), ]; whitelisted_lints.extend(lint_opts.iter().map(|(lint, _)| lint).cloned()); @@ -419,7 +419,7 @@ pub fn run_core(options: RustdocOptions) -> (clean::Crate, RenderInfo, RenderOpt https://doc.rust-lang.org/nightly/rustdoc/how-to-write-documentation\ .html"; tcx.struct_lint_node( - rustc_lint::builtin::MISSING_CRATE_LEVEL_DOC, + rustc_lint::builtin::MISSING_CRATE_LEVEL_DOCS, ctxt.as_local_hir_id(m.def_id).unwrap(), |lint| { let mut diag = lint.build( diff --git a/src/test/rustdoc-ui/no-crate-level-doc-lint.rs b/src/test/rustdoc-ui/no-crate-level-doc-lint.rs index c65af73ead1e5..152a7cd88bcb1 100644 --- a/src/test/rustdoc-ui/no-crate-level-doc-lint.rs +++ b/src/test/rustdoc-ui/no-crate-level-doc-lint.rs @@ -1,3 +1,3 @@ -#![deny(missing_crate_level_doc)] +#![deny(missing_crate_level_docs)] pub fn foo() {} diff --git a/src/test/rustdoc-ui/no-crate-level-doc-lint.stderr b/src/test/rustdoc-ui/no-crate-level-doc-lint.stderr index f8d3723e7b0b4..6e7e2fb3eb73f 100644 --- a/src/test/rustdoc-ui/no-crate-level-doc-lint.stderr +++ b/src/test/rustdoc-ui/no-crate-level-doc-lint.stderr @@ -3,8 +3,8 @@ error: no documentation found for this crate's top-level module note: the lint level is defined here --> $DIR/no-crate-level-doc-lint.rs:1:9 | -LL | #![deny(missing_crate_level_doc)] - | ^^^^^^^^^^^^^^^^^^^^^^^ +LL | #![deny(missing_crate_level_docs)] + | ^^^^^^^^^^^^^^^^^^^^^^^^ = help: The following guide may be of use: https://doc.rust-lang.org/nightly/rustdoc/how-to-write-documentation.html