diff options
Diffstat (limited to 'src')
| -rw-r--r-- | src/doc/rustdoc/src/lints.md | 35 | ||||
| -rw-r--r-- | src/librustdoc/core.rs | 5 | ||||
| -rw-r--r-- | src/librustdoc/lint.rs | 12 | ||||
| -rw-r--r-- | src/test/rustdoc-ui/check.stderr | 13 | ||||
| -rw-r--r-- | src/test/rustdoc-ui/no-crate-level-doc-lint.rs | 4 | ||||
| -rw-r--r-- | src/test/rustdoc-ui/no-crate-level-doc-lint.stderr | 6 |
6 files changed, 53 insertions, 22 deletions
diff --git a/src/doc/rustdoc/src/lints.md b/src/doc/rustdoc/src/lints.md index cce3623dc8f..174db711bce 100644 --- a/src/doc/rustdoc/src/lints.md +++ b/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 diff --git a/src/librustdoc/core.rs b/src/librustdoc/core.rs index 5313f8553a8..9580a6d1ddc 100644 --- a/src/librustdoc/core.rs +++ b/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 = diff --git a/src/librustdoc/lint.rs b/src/librustdoc/lint.rs index 7d95561d039..e8806c1b6d7 100644 --- a/src/librustdoc/lint.rs +++ b/src/librustdoc/lint.rs @@ -105,6 +105,17 @@ declare_rustdoc_lint! { } 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 /// lint, see the documentation in the [rustdoc book]. @@ -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, ] }); diff --git a/src/test/rustdoc-ui/check.stderr b/src/test/rustdoc-ui/check.stderr index 3c29a45a64a..e6ba9df9b05 100644 --- a/src/test/rustdoc-ui/check.stderr +++ b/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 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 152a7cd88bc..3939ec6827a 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,5 @@ -#![deny(missing_crate_level_docs)] +// error-pattern: no documentation found +#![deny(rustdoc::missing_crate_level_docs)] +//^~ NOTE defined here 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 6e7e2fb3eb7..55ead1a55cf 100644 --- a/src/test/rustdoc-ui/no-crate-level-doc-lint.stderr +++ b/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 |