Skip to content

Commit

Permalink
Rollup merge of rust-lang#80527 - jyn514:rustdoc-lints, r=GuillaumeGomez
Browse files Browse the repository at this point in the history
Make rustdoc lints a tool lint instead of built-in

- Rename `broken_intra_doc_links` to `rustdoc::broken_intra_doc_links` (and similar for other rustdoc lints; I don't expect any others to be used frequently, though).
- Ensure that the old lint names still work and give deprecation errors
- Register lints even when running doctests
- Move lint machinery into a separate file
- Add `declare_rustdoc_lint!` macro

Unblocks rust-lang#80300, rust-lang#79816, rust-lang#80965. Makes the strangeness in rust-lang#77364 more apparent to the end user (note that `missing_docs` is *not* moved to rustdoc in this PR). Closes rust-lang#78786.

## Current status

This is blocked on rust-lang#82620 (see rust-lang#80527 (comment))
  • Loading branch information
Dylan-DPC authored Mar 2, 2021
2 parents 847cda6 + 75efb6e commit 2158634
Show file tree
Hide file tree
Showing 86 changed files with 495 additions and 339 deletions.
2 changes: 1 addition & 1 deletion compiler/rustc_ast/src/attr/mod.rs
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ impl MarkedAttrs {
}

pub fn is_known_lint_tool(m_item: Ident) -> bool {
[sym::clippy, sym::rustc].contains(&m_item.name)
[sym::clippy, sym::rustc, sym::rustdoc].contains(&m_item.name)
}

impl NestedMetaItem {
Expand Down
3 changes: 2 additions & 1 deletion compiler/rustc_error_codes/src/lib.rs
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
#![deny(invalid_codeblock_attributes)]
#![cfg_attr(bootstrap, deny(invalid_codeblock_attributes))]
#![cfg_attr(not(bootstrap), deny(rustdoc::invalid_codeblock_attributes))]
//! This library is used to gather all error codes into one place,
//! the goal being to make their maintenance easier.

Expand Down
6 changes: 5 additions & 1 deletion compiler/rustc_lint/src/context.rs
Original file line number Diff line number Diff line change
Expand Up @@ -89,6 +89,7 @@ impl SessionLintStore for LintStore {
}

/// The target of the `by_name` map, which accounts for renaming/deprecation.
#[derive(Debug)]
enum TargetLint {
/// A direct lint target
Id(LintId),
Expand Down Expand Up @@ -470,7 +471,10 @@ impl LintStore {
Some(&Id(ref id)) => {
CheckLintNameResult::Tool(Err((Some(slice::from_ref(id)), complete_name)))
}
_ => CheckLintNameResult::NoLint(None),
Some(other) => {
tracing::debug!("got renamed lint {:?}", other);
CheckLintNameResult::NoLint(None)
}
}
}
}
Expand Down
38 changes: 23 additions & 15 deletions compiler/rustc_lint/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -69,9 +69,7 @@ use rustc_hir::def_id::LocalDefId;
use rustc_middle::ty::query::Providers;
use rustc_middle::ty::TyCtxt;
use rustc_session::lint::builtin::{
BARE_TRAIT_OBJECTS, BROKEN_INTRA_DOC_LINKS, ELIDED_LIFETIMES_IN_PATHS,
EXPLICIT_OUTLIVES_REQUIREMENTS, INVALID_CODEBLOCK_ATTRIBUTES, INVALID_HTML_TAGS,
MISSING_DOC_CODE_EXAMPLES, NON_AUTOLINKS, PRIVATE_DOC_TESTS,
BARE_TRAIT_OBJECTS, ELIDED_LIFETIMES_IN_PATHS, EXPLICIT_OUTLIVES_REQUIREMENTS,
};
use rustc_span::symbol::{Ident, Symbol};
use rustc_span::Span;
Expand Down Expand Up @@ -314,17 +312,6 @@ fn register_builtins(store: &mut LintStore, no_interleave_lints: bool) {
// MACRO_USE_EXTERN_CRATE
);

add_lint_group!(
"rustdoc",
NON_AUTOLINKS,
BROKEN_INTRA_DOC_LINKS,
PRIVATE_INTRA_DOC_LINKS,
INVALID_CODEBLOCK_ATTRIBUTES,
MISSING_DOC_CODE_EXAMPLES,
PRIVATE_DOC_TESTS,
INVALID_HTML_TAGS
);

// Register renamed and removed lints.
store.register_renamed("single_use_lifetime", "single_use_lifetimes");
store.register_renamed("elided_lifetime_in_path", "elided_lifetimes_in_paths");
Expand All @@ -334,8 +321,29 @@ fn register_builtins(store: &mut LintStore, no_interleave_lints: bool) {
store.register_renamed("async_idents", "keyword_idents");
store.register_renamed("exceeding_bitshifts", "arithmetic_overflow");
store.register_renamed("redundant_semicolon", "redundant_semicolons");
store.register_renamed("intra_doc_link_resolution_failure", "broken_intra_doc_links");
store.register_renamed("overlapping_patterns", "overlapping_range_endpoints");

// These were moved to tool lints, but rustc still sees them when compiling normally, before
// tool lints are registered, so `check_tool_name_for_backwards_compat` doesn't work. Use
// `register_removed` explicitly.
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",
"invalid_html_tags",
"non_autolinks",
];
for rustdoc_lint in RUSTDOC_LINTS {
store.register_removed(rustdoc_lint, &format!("use `rustdoc::{}` instead", rustdoc_lint));
}
store.register_removed(
"intra_doc_link_resolution_failure",
"use `rustdoc::broken_intra_doc_links` instead",
);

store.register_removed("unknown_features", "replaced by an error");
store.register_removed("unsigned_negation", "replaced by negate_unsigned feature gate");
store.register_removed("negate_unsigned", "cast a signed value instead");
Expand Down
95 changes: 0 additions & 95 deletions compiler/rustc_lint_defs/src/builtin.rs
Original file line number Diff line number Diff line change
Expand Up @@ -1875,93 +1875,6 @@ declare_lint! {
"detects labels that are never used"
}

declare_lint! {
/// The `broken_intra_doc_links` lint detects failures in resolving
/// intra-doc link targets. This is a `rustdoc` only lint, see the
/// documentation in the [rustdoc book].
///
/// [rustdoc book]: ../../../rustdoc/lints.html#broken_intra_doc_links
pub BROKEN_INTRA_DOC_LINKS,
Warn,
"failures in resolving intra-doc link targets"
}

declare_lint! {
/// This is a subset of `broken_intra_doc_links` that warns when linking from
/// a public item to a private one. This is a `rustdoc` only lint, see the
/// documentation in the [rustdoc book].
///
/// [rustdoc book]: ../../../rustdoc/lints.html#private_intra_doc_links
pub PRIVATE_INTRA_DOC_LINKS,
Warn,
"linking from a public item to a private one"
}

declare_lint! {
/// The `invalid_codeblock_attributes` lint detects code block attributes
/// in documentation examples that have potentially mis-typed values. This
/// is a `rustdoc` only lint, see the documentation in the [rustdoc book].
///
/// [rustdoc book]: ../../../rustdoc/lints.html#invalid_codeblock_attributes
pub INVALID_CODEBLOCK_ATTRIBUTES,
Warn,
"codeblock attribute looks a lot like a known one"
}

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 `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].
///
/// [rustdoc book]: ../../../rustdoc/lints.html#missing_doc_code_examples
pub MISSING_DOC_CODE_EXAMPLES,
Allow,
"detects publicly-exported items without code samples in their documentation"
}

declare_lint! {
/// The `private_doc_tests` lint detects code samples in docs of private
/// items not documented by `rustdoc`. This is a `rustdoc` only lint, see
/// the documentation in the [rustdoc book].
///
/// [rustdoc book]: ../../../rustdoc/lints.html#private_doc_tests
pub PRIVATE_DOC_TESTS,
Allow,
"detects code samples in docs of private items not documented by rustdoc"
}

declare_lint! {
/// The `invalid_html_tags` lint detects invalid HTML tags. This is a
/// `rustdoc` only lint, see the documentation in the [rustdoc book].
///
/// [rustdoc book]: ../../../rustdoc/lints.html#invalid_html_tags
pub INVALID_HTML_TAGS,
Allow,
"detects invalid HTML tags in doc comments"
}

declare_lint! {
/// The `non_autolinks` lint detects when a URL could be written using
/// only angle brackets. This is a `rustdoc` only lint, see the
/// documentation in the [rustdoc book].
///
/// [rustdoc book]: ../../../rustdoc/lints.html#non_autolinks
pub NON_AUTOLINKS,
Warn,
"detects URLs that could be written using only angle brackets"
}

declare_lint! {
/// The `where_clauses_object_safety` lint detects for [object safety] of
/// [where clauses].
Expand Down Expand Up @@ -3020,14 +2933,6 @@ declare_lint_pass! {
ABSOLUTE_PATHS_NOT_STARTING_WITH_CRATE,
UNSTABLE_NAME_COLLISIONS,
IRREFUTABLE_LET_PATTERNS,
BROKEN_INTRA_DOC_LINKS,
PRIVATE_INTRA_DOC_LINKS,
INVALID_CODEBLOCK_ATTRIBUTES,
MISSING_CRATE_LEVEL_DOCS,
MISSING_DOC_CODE_EXAMPLES,
INVALID_HTML_TAGS,
PRIVATE_DOC_TESTS,
NON_AUTOLINKS,
WHERE_CLAUSES_OBJECT_SAFETY,
PROC_MACRO_DERIVE_RESOLUTION_FALLBACK,
MACRO_USE_EXTERN_CRATE,
Expand Down
1 change: 1 addition & 0 deletions compiler/rustc_span/src/symbol.rs
Original file line number Diff line number Diff line change
Expand Up @@ -1021,6 +1021,7 @@ symbols! {
rustc_then_this_would_need,
rustc_unsafe_specialization_marker,
rustc_variance,
rustdoc,
rustfmt,
rvalue_static_promotion,
sanitize,
Expand Down
3 changes: 2 additions & 1 deletion library/core/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -297,7 +297,8 @@ pub mod primitive;
unused_imports,
unsafe_op_in_unsafe_fn
)]
#[allow(non_autolinks)]
#[cfg_attr(bootstrap, allow(non_autolinks))]
#[cfg_attr(not(bootstrap), allow(rustdoc::non_autolinks))]
// FIXME: This annotation should be moved into rust-lang/stdarch after clashing_extern_declarations is
// merged. It currently cannot because bootstrap fails as the lint hasn't been defined yet.
#[allow(clashing_extern_declarations)]
Expand Down
18 changes: 15 additions & 3 deletions src/bootstrap/builder.rs
Original file line number Diff line number Diff line change
Expand Up @@ -735,8 +735,15 @@ impl<'a> Builder<'a> {
.env("RUSTDOC_LIBDIR", self.rustc_libdir(compiler))
.env("CFG_RELEASE_CHANNEL", &self.config.channel)
.env("RUSTDOC_REAL", self.rustdoc(compiler))
.env("RUSTC_BOOTSTRAP", "1")
.arg("-Winvalid_codeblock_attributes");
.env("RUSTC_BOOTSTRAP", "1");

// cfg(bootstrap), can be removed on the next beta bump
if compiler.stage == 0 {
cmd.arg("-Winvalid_codeblock_attributes");
} else {
cmd.arg("-Wrustdoc::invalid_codeblock_attributes");
}

if self.config.deny_warnings {
cmd.arg("-Dwarnings");
}
Expand Down Expand Up @@ -1292,7 +1299,12 @@ impl<'a> Builder<'a> {
// fixed via better support from Cargo.
cargo.env("RUSTC_LINT_FLAGS", lint_flags.join(" "));

rustdocflags.arg("-Winvalid_codeblock_attributes");
// cfg(bootstrap), can be removed on the next beta bump
if compiler.stage == 0 {
rustdocflags.arg("-Winvalid_codeblock_attributes");
} else {
rustdocflags.arg("-Wrustdoc::invalid_codeblock_attributes");
}
}

if mode == Mode::Rustc {
Expand Down
35 changes: 21 additions & 14 deletions src/doc/rustdoc/src/lints.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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`]
Expand Down Expand Up @@ -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`
```

Expand All @@ -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
```

Expand Down Expand Up @@ -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:
Expand All @@ -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() {}
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
```
Expand All @@ -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>
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand Down
Loading

0 comments on commit 2158634

Please sign in to comment.