Address review comments

- Move MISSING_CRATE_LEVEL_DOCS to rustdoc directly
- Update documentation

This also takes the opportunity to make the `no-crate-level-doc-lint`
test more specific.

Author: jyn514

compiler/rustc_lint/src/lib.rs

@@ -329,6 +329,7 @@ fn register_builtins(store: &mut LintStore, no_interleave_lints: bool) {
     const RUSTDOC_LINTS: &[&str] = &[
         "broken_intra_doc_links",
         "private_intra_doc_links",
+        "missing_crate_level_docs",
         "missing_doc_code_examples",
         "private_doc_tests",
         "invalid_codeblock_attributes",

compiler/rustc_lint_defs/src/builtin.rs

@@ -1875,17 +1875,6 @@ declare_lint! {
     "detects labels that are never used"
 }
 
-declare_lint! {
-    /// The `missing_crate_level_docs` lint detects if documentation is
-    /// missing at the crate root. This is a `rustdoc` only lint, see the
-    /// documentation in the [rustdoc book].
-    ///
-    /// [rustdoc book]: ../../../rustdoc/lints.html#missing_crate_level_docs
-    pub MISSING_CRATE_LEVEL_DOCS,
-    Allow,
-    "detects crates with no crate-level documentation"
-}
-
 declare_lint! {
     /// The `where_clauses_object_safety` lint detects for [object safety] of
     /// [where clauses].
@@ -2944,7 +2933,6 @@ declare_lint_pass! {
         ABSOLUTE_PATHS_NOT_STARTING_WITH_CRATE,
         UNSTABLE_NAME_COLLISIONS,
         IRREFUTABLE_LET_PATTERNS,
-        MISSING_CRATE_LEVEL_DOCS,
         WHERE_CLAUSES_OBJECT_SAFETY,
         PROC_MACRO_DERIVE_RESOLUTION_FALLBACK,
         MACRO_USE_EXTERN_CRATE,

src/doc/rustdoc/src/lints.md

@@ -4,12 +4,13 @@
 can use them like any other lints by doing this:
 
 ```rust
-#![allow(missing_docs)] // allows the lint, no diagnostics will be reported
-#![warn(missing_docs)] // warn if there are missing docs
-#![deny(missing_docs)] // error if there are missing docs
-# //! Crate docs.
+#![allow(rustdoc::broken_intra_doc_links)] // allows the lint, no diagnostics will be reported
+#![warn(rustdoc::broken_intra_doc_links)] // warn if there are broken intra-doc links
+#![deny(rustdoc::broken_intra_doc_links)] // error if there are broken intra-doc links
 ```
 
+Note that, except for `missing_docs`, these lints are only available when running `rustdoc`, not `rustc`.
+
 Here is the list of the lints provided by `rustdoc`:
 
 ## broken_intra_doc_links
@@ -51,7 +52,7 @@ warning: `Foo` is both an enum and a function
 1 | /// [`Foo`]
   |      ^^^^^ ambiguous link
   |
-  = note: `#[warn(broken_intra_doc_links)]` on by default
+  = note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default
 help: to link to the enum, prefix with the item type
   |
 1 | /// [`enum@Foo`]
@@ -83,7 +84,7 @@ warning: public documentation for `public` links to private item `private`
 1 | /// [private]
   |      ^^^^^^^ this item is private
   |
-  = note: `#[warn(private_intra_doc_links)]` on by default
+  = note: `#[warn(rustdoc::private_intra_doc_links)]` on by default
   = note: this link will resolve properly if you pass `--document-private-items`
 ```
 
@@ -97,7 +98,7 @@ warning: public documentation for `public` links to private item `private`
 1 | /// [private]
   |      ^^^^^^^ this item is private
   |
-  = note: `#[warn(private_intra_doc_links)]` on by default
+  = note: `#[warn(rustdoc::private_intra_doc_links)]` on by default
   = note: this link resolves only because you passed `--document-private-items`, but will break without
 ```
 
@@ -125,13 +126,15 @@ warning: missing documentation for a function
    | ^^^^^^^^^^^^^^^^^^^^^
 ```
 
+Note that unlike other rustdoc lints, this lint is also available from `rustc` directly.
+
 ## missing_crate_level_docs
 
 This lint is **allowed by default**. It detects if there is no documentation
 at the crate root. For example:
 
 ```rust
-#![warn(missing_crate_level_docs)]
+#![warn(rustdoc::missing_crate_level_docs)]
 ```
 
 This will generate the following warning:
@@ -155,7 +158,7 @@ This lint is **allowed by default** and is **nightly-only**. It detects when a d
 is missing a code example. For example:
 
 ```rust
-#![warn(missing_doc_code_examples)]
+#![warn(rustdoc::missing_doc_code_examples)]
 
 /// There is no code example!
 pub fn no_code_example() {}
@@ -191,7 +194,7 @@ This lint is **allowed by default**. It detects documentation tests when they
 are on a private item. For example:
 
 ```rust
-#![warn(private_doc_tests)]
+#![warn(rustdoc::private_doc_tests)]
 
 mod foo {
     /// private doc test
@@ -245,7 +248,7 @@ warning: unknown attribute `should-panic`. Did you mean `should_panic`?
 5 | | /// ```
   | |_______^
   |
-  = note: `#[warn(invalid_codeblock_attributes)]` on by default
+  = note: `#[warn(rustdoc::invalid_codeblock_attributes)]` on by default
   = help: the code block will either not be tested if not marked as a rust one or won't fail if it doesn't panic when running
 ```
 
@@ -258,7 +261,7 @@ This lint is **allowed by default** and is **nightly-only**. It detects unclosed
 or invalid HTML tags. For example:
 
 ```rust
-#![warn(invalid_html_tags)]
+#![warn(rustdoc::invalid_html_tags)]
 
 /// <h1>
 /// </script>
@@ -275,7 +278,11 @@ warning: unopened HTML tag `script`
 2 | | /// </script>
   | |_____________^
   |
-  = note: `#[warn(invalid_html_tags)]` on by default
+  note: the lint level is defined here
+ --> foo.rs:1:9
+  |
+1 | #![warn(rustdoc::invalid_html_tags)]
+  |         ^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 warning: unclosed HTML tag `h1`
  --> foo.rs:1:1
@@ -310,7 +317,7 @@ warning: this URL is not a hyperlink
 1 | /// http://example.org
   |     ^^^^^^^^^^^^^^^^^^ help: use an automatic link instead: `<http://example.org>`
   |
-  = note: `#[warn(non_autolinks)]` on by default
+  = note: `#[warn(rustdoc::non_autolinks)]` on by default
 
 warning: unneeded long form for URL
  --> foo.rs:2:5

src/librustdoc/core.rs

@@ -260,9 +260,8 @@ crate fn create_config(
     // By default, rustdoc ignores all lints.
     // Specifically unblock lints relevant to documentation or the lint machinery itself.
     let mut lints_to_show = vec![
-        // it's unclear whether these should be part of rustdoc directly
+        // it's unclear whether this should be part of rustdoc directly (#77364)
         rustc_lint::builtin::MISSING_DOCS.name.to_string(),
-        rustc_lint::builtin::MISSING_CRATE_LEVEL_DOCS.name.to_string(),
         // these are definitely not part of rustdoc, but we want to warn on them anyway.
         rustc_lint::builtin::RENAMED_AND_REMOVED_LINTS.name.to_string(),
         rustc_lint::builtin::UNKNOWN_LINTS.name.to_string(),
@@ -482,7 +481,7 @@ crate fn run_global_ctxt(
             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_DOCS,
+                crate::lint::MISSING_CRATE_LEVEL_DOCS,
                 ctxt.as_local_hir_id(m.def_id).unwrap(),
                 |lint| {
                     let mut diag =

src/librustdoc/lint.rs

@@ -104,6 +104,17 @@ declare_rustdoc_lint! {
     "codeblock attribute looks a lot like a known one"
 }
 
+declare_rustdoc_lint! {
+    /// The `missing_crate_level_docs` lint detects if documentation is
+    /// missing at the crate root. This is a `rustdoc` only lint, see the
+    /// documentation in the [rustdoc book].
+    ///
+    /// [rustdoc book]: ../../../rustdoc/lints.html#missing_crate_level_docs
+    MISSING_CRATE_LEVEL_DOCS,
+    Allow,
+    "detects crates with no crate-level documentation"
+}
+
 declare_rustdoc_lint! {
     /// The `missing_doc_code_examples` lint detects publicly-exported items
     /// without code samples in their documentation. This is a `rustdoc` only
@@ -156,6 +167,7 @@ crate static RUSTDOC_LINTS: Lazy<Vec<&'static Lint>> = Lazy::new(|| {
         INVALID_CODEBLOCK_ATTRIBUTES,
         INVALID_HTML_TAGS,
         NON_AUTOLINKS,
+        MISSING_CRATE_LEVEL_DOCS,
     ]
 });
 

src/test/rustdoc-ui/check.stderr

@@ -21,6 +21,17 @@ warning: missing documentation for a function
 LL | pub fn foo() {}
    | ^^^^^^^^^^^^
 
+warning: no documentation found for this crate's top-level module
+   |
+note: the lint level is defined here
+  --> $DIR/check.rs:7:9
+   |
+LL | #![warn(rustdoc)]
+   |         ^^^^^^^
+   = note: `#[warn(rustdoc::missing_crate_level_docs)]` implied by `#[warn(rustdoc)]`
+   = help: The following guide may be of use:
+           https://doc.rust-lang.org/nightly/rustdoc/how-to-write-documentation.html
+
 warning: missing code example in this documentation
   --> $DIR/check.rs:4:1
    |
@@ -45,5 +56,5 @@ warning: missing code example in this documentation
 LL | pub fn foo() {}
    | ^^^^^^^^^^^^^^^
 
-warning: 4 warnings emitted
+warning: 5 warnings emitted
 

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

@@ -1,3 +1,5 @@
-#![deny(missing_crate_level_docs)]
+// error-pattern: no documentation found
+#![deny(rustdoc::missing_crate_level_docs)]
+//^~ NOTE defined here
 
 pub fn foo() {}

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

@@ -1,10 +1,10 @@
 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
+  --> $DIR/no-crate-level-doc-lint.rs:2:9
    |
-LL | #![deny(missing_crate_level_docs)]
-   |         ^^^^^^^^^^^^^^^^^^^^^^^^
+LL | #![deny(rustdoc::missing_crate_level_docs)]
+   |         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    = help: The following guide may be of use:
            https://doc.rust-lang.org/nightly/rustdoc/how-to-write-documentation.html