Skip to content

Commit 0517ea7

Browse files
committed
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.
1 parent e8ddfda commit 0517ea7

File tree

8 files changed

+54
-34
lines changed

8 files changed

+54
-34
lines changed

compiler/rustc_lint/src/lib.rs

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -329,6 +329,7 @@ fn register_builtins(store: &mut LintStore, no_interleave_lints: bool) {
329329
const RUSTDOC_LINTS: &[&str] = &[
330330
"broken_intra_doc_links",
331331
"private_intra_doc_links",
332+
"missing_crate_level_docs",
332333
"missing_doc_code_examples",
333334
"private_doc_tests",
334335
"invalid_codeblock_attributes",

compiler/rustc_lint_defs/src/builtin.rs

Lines changed: 0 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1875,17 +1875,6 @@ declare_lint! {
18751875
"detects labels that are never used"
18761876
}
18771877

1878-
declare_lint! {
1879-
/// The `missing_crate_level_docs` lint detects if documentation is
1880-
/// missing at the crate root. This is a `rustdoc` only lint, see the
1881-
/// documentation in the [rustdoc book].
1882-
///
1883-
/// [rustdoc book]: ../../../rustdoc/lints.html#missing_crate_level_docs
1884-
pub MISSING_CRATE_LEVEL_DOCS,
1885-
Allow,
1886-
"detects crates with no crate-level documentation"
1887-
}
1888-
18891878
declare_lint! {
18901879
/// The `where_clauses_object_safety` lint detects for [object safety] of
18911880
/// [where clauses].
@@ -2944,7 +2933,6 @@ declare_lint_pass! {
29442933
ABSOLUTE_PATHS_NOT_STARTING_WITH_CRATE,
29452934
UNSTABLE_NAME_COLLISIONS,
29462935
IRREFUTABLE_LET_PATTERNS,
2947-
MISSING_CRATE_LEVEL_DOCS,
29482936
WHERE_CLAUSES_OBJECT_SAFETY,
29492937
PROC_MACRO_DERIVE_RESOLUTION_FALLBACK,
29502938
MACRO_USE_EXTERN_CRATE,

src/doc/rustdoc/src/lints.md

Lines changed: 21 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -4,12 +4,13 @@
44
can use them like any other lints by doing this:
55

66
```rust
7-
#![allow(missing_docs)] // allows the lint, no diagnostics will be reported
8-
#![warn(missing_docs)] // warn if there are missing docs
9-
#![deny(missing_docs)] // error if there are missing docs
10-
# //! Crate docs.
7+
#![allow(rustdoc::broken_intra_doc_links)] // allows the lint, no diagnostics will be reported
8+
#![warn(rustdoc::broken_intra_doc_links)] // warn if there are broken intra-doc links
9+
#![deny(rustdoc::broken_intra_doc_links)] // error if there are broken intra-doc links
1110
```
1211

12+
Note that, except for `missing_docs`, these lints are only available when running `rustdoc`, not `rustc`.
13+
1314
Here is the list of the lints provided by `rustdoc`:
1415

1516
## broken_intra_doc_links
@@ -51,7 +52,7 @@ warning: `Foo` is both an enum and a function
5152
1 | /// [`Foo`]
5253
| ^^^^^ ambiguous link
5354
|
54-
= note: `#[warn(broken_intra_doc_links)]` on by default
55+
= note: `#[warn(rustdoc::broken_intra_doc_links)]` on by default
5556
help: to link to the enum, prefix with the item type
5657
|
5758
1 | /// [`enum@Foo`]
@@ -83,7 +84,7 @@ warning: public documentation for `public` links to private item `private`
8384
1 | /// [private]
8485
| ^^^^^^^ this item is private
8586
|
86-
= note: `#[warn(private_intra_doc_links)]` on by default
87+
= note: `#[warn(rustdoc::private_intra_doc_links)]` on by default
8788
= note: this link will resolve properly if you pass `--document-private-items`
8889
```
8990

@@ -97,7 +98,7 @@ warning: public documentation for `public` links to private item `private`
9798
1 | /// [private]
9899
| ^^^^^^^ this item is private
99100
|
100-
= note: `#[warn(private_intra_doc_links)]` on by default
101+
= note: `#[warn(rustdoc::private_intra_doc_links)]` on by default
101102
= note: this link resolves only because you passed `--document-private-items`, but will break without
102103
```
103104

@@ -125,13 +126,15 @@ warning: missing documentation for a function
125126
| ^^^^^^^^^^^^^^^^^^^^^
126127
```
127128

129+
Note that unlike other rustdoc lints, this lint is also available from `rustc` directly.
130+
128131
## missing_crate_level_docs
129132

130133
This lint is **allowed by default**. It detects if there is no documentation
131134
at the crate root. For example:
132135

133136
```rust
134-
#![warn(missing_crate_level_docs)]
137+
#![warn(rustdoc::missing_crate_level_docs)]
135138
```
136139

137140
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
155158
is missing a code example. For example:
156159

157160
```rust
158-
#![warn(missing_doc_code_examples)]
161+
#![warn(rustdoc::missing_doc_code_examples)]
159162

160163
/// There is no code example!
161164
pub fn no_code_example() {}
@@ -191,7 +194,7 @@ This lint is **allowed by default**. It detects documentation tests when they
191194
are on a private item. For example:
192195

193196
```rust
194-
#![warn(private_doc_tests)]
197+
#![warn(rustdoc::private_doc_tests)]
195198

196199
mod foo {
197200
/// private doc test
@@ -245,7 +248,7 @@ warning: unknown attribute `should-panic`. Did you mean `should_panic`?
245248
5 | | /// ```
246249
| |_______^
247250
|
248-
= note: `#[warn(invalid_codeblock_attributes)]` on by default
251+
= note: `#[warn(rustdoc::invalid_codeblock_attributes)]` on by default
249252
= 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
250253
```
251254

@@ -258,7 +261,7 @@ This lint is **allowed by default** and is **nightly-only**. It detects unclosed
258261
or invalid HTML tags. For example:
259262

260263
```rust
261-
#![warn(invalid_html_tags)]
264+
#![warn(rustdoc::invalid_html_tags)]
262265

263266
/// <h1>
264267
/// </script>
@@ -275,7 +278,11 @@ warning: unopened HTML tag `script`
275278
2 | | /// </script>
276279
| |_____________^
277280
|
278-
= note: `#[warn(invalid_html_tags)]` on by default
281+
note: the lint level is defined here
282+
--> foo.rs:1:9
283+
|
284+
1 | #![warn(rustdoc::invalid_html_tags)]
285+
| ^^^^^^^^^^^^^^^^^^^^^^^^^^
279286
280287
warning: unclosed HTML tag `h1`
281288
--> foo.rs:1:1
@@ -310,7 +317,7 @@ warning: this URL is not a hyperlink
310317
1 | /// http://example.org
311318
| ^^^^^^^^^^^^^^^^^^ help: use an automatic link instead: `<http://example.org>`
312319
|
313-
= note: `#[warn(non_autolinks)]` on by default
320+
= note: `#[warn(rustdoc::non_autolinks)]` on by default
314321
315322
warning: unneeded long form for URL
316323
--> foo.rs:2:5

src/librustdoc/core.rs

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -260,9 +260,8 @@ crate fn create_config(
260260
// By default, rustdoc ignores all lints.
261261
// Specifically unblock lints relevant to documentation or the lint machinery itself.
262262
let mut lints_to_show = vec![
263-
// it's unclear whether these should be part of rustdoc directly
263+
// it's unclear whether this should be part of rustdoc directly (#77364)
264264
rustc_lint::builtin::MISSING_DOCS.name.to_string(),
265-
rustc_lint::builtin::MISSING_CRATE_LEVEL_DOCS.name.to_string(),
266265
// these are definitely not part of rustdoc, but we want to warn on them anyway.
267266
rustc_lint::builtin::RENAMED_AND_REMOVED_LINTS.name.to_string(),
268267
rustc_lint::builtin::UNKNOWN_LINTS.name.to_string(),
@@ -482,7 +481,7 @@ crate fn run_global_ctxt(
482481
let help = "The following guide may be of use:\n\
483482
https://doc.rust-lang.org/nightly/rustdoc/how-to-write-documentation.html";
484483
tcx.struct_lint_node(
485-
rustc_lint::builtin::MISSING_CRATE_LEVEL_DOCS,
484+
crate::lint::MISSING_CRATE_LEVEL_DOCS,
486485
ctxt.as_local_hir_id(m.def_id).unwrap(),
487486
|lint| {
488487
let mut diag =

src/librustdoc/lint.rs

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -104,6 +104,17 @@ declare_rustdoc_lint! {
104104
"codeblock attribute looks a lot like a known one"
105105
}
106106

107+
declare_rustdoc_lint! {
108+
/// The `missing_crate_level_docs` lint detects if documentation is
109+
/// missing at the crate root. This is a `rustdoc` only lint, see the
110+
/// documentation in the [rustdoc book].
111+
///
112+
/// [rustdoc book]: ../../../rustdoc/lints.html#missing_crate_level_docs
113+
MISSING_CRATE_LEVEL_DOCS,
114+
Allow,
115+
"detects crates with no crate-level documentation"
116+
}
117+
107118
declare_rustdoc_lint! {
108119
/// The `missing_doc_code_examples` lint detects publicly-exported items
109120
/// 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(|| {
156167
INVALID_CODEBLOCK_ATTRIBUTES,
157168
INVALID_HTML_TAGS,
158169
NON_AUTOLINKS,
170+
MISSING_CRATE_LEVEL_DOCS,
159171
]
160172
});
161173

src/test/rustdoc-ui/check.stderr

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,17 @@ warning: missing documentation for a function
2121
LL | pub fn foo() {}
2222
| ^^^^^^^^^^^^
2323

24+
warning: no documentation found for this crate's top-level module
25+
|
26+
note: the lint level is defined here
27+
--> $DIR/check.rs:7:9
28+
|
29+
LL | #![warn(rustdoc)]
30+
| ^^^^^^^
31+
= note: `#[warn(rustdoc::missing_crate_level_docs)]` implied by `#[warn(rustdoc)]`
32+
= help: The following guide may be of use:
33+
https://doc.rust-lang.org/nightly/rustdoc/how-to-write-documentation.html
34+
2435
warning: missing code example in this documentation
2536
--> $DIR/check.rs:4:1
2637
|
@@ -45,5 +56,5 @@ warning: missing code example in this documentation
4556
LL | pub fn foo() {}
4657
| ^^^^^^^^^^^^^^^
4758

48-
warning: 4 warnings emitted
59+
warning: 5 warnings emitted
4960

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1-
#![deny(missing_crate_level_docs)]
1+
// error-pattern: no documentation found
2+
#![deny(rustdoc::missing_crate_level_docs)]
3+
//^~ NOTE defined here
24

35
pub fn foo() {}

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

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
error: no documentation found for this crate's top-level module
22
|
33
note: the lint level is defined here
4-
--> $DIR/no-crate-level-doc-lint.rs:1:9
4+
--> $DIR/no-crate-level-doc-lint.rs:2:9
55
|
6-
LL | #![deny(missing_crate_level_docs)]
7-
| ^^^^^^^^^^^^^^^^^^^^^^^^
6+
LL | #![deny(rustdoc::missing_crate_level_docs)]
7+
| ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
88
= help: The following guide may be of use:
99
https://doc.rust-lang.org/nightly/rustdoc/how-to-write-documentation.html
1010

0 commit comments

Comments
 (0)