Add lint when no doc is present at the crate-level

Author: GuillaumeGomez

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,

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 \

src/test/rustdoc-ui/no-crate-level-doc-lint.rs

@@ -0,0 +1,3 @@
+#![deny(no_crate_level_doc)]
+
+pub fn foo() {}

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
+