From 2c13c68de5dc4d47877069cf65b1f60a5962fe71 Mon Sep 17 00:00:00 2001 From: Alexis Bourget Date: Mon, 28 Dec 2020 23:07:20 +0100 Subject: [PATCH 1/4] New rustdoc lint to respect -Dwarnings correctly This adds a new lint to `rustc` that is used in rustdoc when a code block is empty or cannot be parsed as valid Rust code. Previously this was unconditionally a warning. As such some documentation comments were (unknowingly) abusing this to pass despite the `-Dwarnings` used when compiling `rustc`, this should not be the case anymore. --- .../src/borrow_check/region_infer/mod.rs | 2 +- .../rustc_trait_selection/src/opaque_types.rs | 1 + compiler/rustc_typeck/src/check/upvar.rs | 4 +- src/doc/rustdoc/src/lints.md | 37 ++++++++ src/librustdoc/lint.rs | 13 +++ .../passes/check_code_block_syntax.rs | 92 ++++++++++++------- src/test/rustdoc-ui/ignore-block-help.stderr | 5 +- src/test/rustdoc-ui/invalid-syntax.stderr | 1 + 8 files changed, 115 insertions(+), 40 deletions(-) diff --git a/compiler/rustc_mir/src/borrow_check/region_infer/mod.rs b/compiler/rustc_mir/src/borrow_check/region_infer/mod.rs index bbd512fd36050..9dc2e3d292359 100644 --- a/compiler/rustc_mir/src/borrow_check/region_infer/mod.rs +++ b/compiler/rustc_mir/src/borrow_check/region_infer/mod.rs @@ -1241,7 +1241,7 @@ impl<'tcx> RegionInferenceContext<'tcx> { /// it. However, it works pretty well in practice. In particular, /// this is needed to deal with projection outlives bounds like /// - /// ```ignore (internal compiler representation so lifetime syntax is invalid) + /// ```text (internal compiler representation so lifetime syntax is invalid) /// >::Item: '1 /// ``` /// diff --git a/compiler/rustc_trait_selection/src/opaque_types.rs b/compiler/rustc_trait_selection/src/opaque_types.rs index fb4a8ce687c4d..7e67bc118ec1e 100644 --- a/compiler/rustc_trait_selection/src/opaque_types.rs +++ b/compiler/rustc_trait_selection/src/opaque_types.rs @@ -46,6 +46,7 @@ pub struct OpaqueTypeDecl<'tcx> { /// type Foo = impl Baz; /// fn bar() -> Foo { /// // ^^^ This is the span we are looking for! + /// } /// ``` /// /// In cases where the fn returns `(impl Trait, impl Trait)` or diff --git a/compiler/rustc_typeck/src/check/upvar.rs b/compiler/rustc_typeck/src/check/upvar.rs index 751eebb9f9564..c0a700aacd458 100644 --- a/compiler/rustc_typeck/src/check/upvar.rs +++ b/compiler/rustc_typeck/src/check/upvar.rs @@ -320,7 +320,7 @@ impl<'a, 'tcx> FnCtxt<'a, 'tcx> { /// /// InferBorrowKind results in a structure like this: /// - /// ``` + /// ```text /// { /// Place(base: hir_id_s, projections: [], ....) -> { /// capture_kind_expr: hir_id_L5, @@ -345,7 +345,7 @@ impl<'a, 'tcx> FnCtxt<'a, 'tcx> { /// ``` /// /// After the min capture analysis, we get: - /// ``` + /// ```text /// { /// hir_id_s -> [ /// Place(base: hir_id_s, projections: [], ....) -> { diff --git a/src/doc/rustdoc/src/lints.md b/src/doc/rustdoc/src/lints.md index a6626679a7d60..7088e60aa07da 100644 --- a/src/doc/rustdoc/src/lints.md +++ b/src/doc/rustdoc/src/lints.md @@ -294,6 +294,43 @@ warning: unclosed HTML tag `h1` warning: 2 warnings emitted ``` +## invalid_rust_codeblock + +This lint **warns by default**. It detects Rust code blocks in documentation +examples that are invalid (e.g. empty, not parsable as Rust). For example: + +```rust +/// Empty code blocks (with and without the `rust` marker): +/// +/// ```rust +/// ``` +/// +/// Unclosed code blocks (with and without the `rust` marker): +/// +/// ```rust +fn main() {} +``` + +Which will give: + +```text +warning: Rust code block is empty +--> src/lib.rs:3:5 +| +3 | /// ```rust +| _____^ +4 | | /// ``` +| |_______^ +| += note: `#[warn(rustdoc::invalid_rust_codeblock)]` on by default + +warning: Rust code block is empty +--> src/lib.rs:8:5 +| +8 | /// ```rust +| ^^^^^^^ +``` + ## bare_urls This lint is **warn-by-default**. It detects URLs which are not links. diff --git a/src/librustdoc/lint.rs b/src/librustdoc/lint.rs index 1b79811d4b075..597efed56e176 100644 --- a/src/librustdoc/lint.rs +++ b/src/librustdoc/lint.rs @@ -157,6 +157,18 @@ declare_rustdoc_lint! { "detects URLs that are not hyperlinks" } +declare_rustdoc_lint! { + /// The `invalid_rust_codeblock` lint detects Rust code blocks in + /// documentation examples that are invalid (e.g. empty, not parsable as + /// Rust code). This is a `rustdoc` only lint, see the documentation in the + /// [rustdoc book]. + /// + /// [rustdoc book]: ../../../rustdoc/lints.html#invalid_rust_codeblock + INVALID_RUST_CODEBLOCK, + Warn, + "codeblock could not be parsed as valid Rust or is empty" +} + crate static RUSTDOC_LINTS: Lazy> = Lazy::new(|| { vec![ BROKEN_INTRA_DOC_LINKS, @@ -164,6 +176,7 @@ crate static RUSTDOC_LINTS: Lazy> = Lazy::new(|| { MISSING_DOC_CODE_EXAMPLES, PRIVATE_DOC_TESTS, INVALID_CODEBLOCK_ATTRIBUTES, + INVALID_RUST_CODEBLOCK, INVALID_HTML_TAGS, BARE_URLS, MISSING_CRATE_LEVEL_DOCS, diff --git a/src/librustdoc/passes/check_code_block_syntax.rs b/src/librustdoc/passes/check_code_block_syntax.rs index 68a66806e0476..d213a4ba52243 100644 --- a/src/librustdoc/passes/check_code_block_syntax.rs +++ b/src/librustdoc/passes/check_code_block_syntax.rs @@ -1,5 +1,6 @@ use rustc_data_structures::sync::{Lock, Lrc}; use rustc_errors::{emitter::Emitter, Applicability, Diagnostic, Handler}; +use rustc_middle::lint::LintDiagnosticBuilder; use rustc_parse::parse_stream_from_source_str; use rustc_session::parse::ParseSess; use rustc_span::source_map::{FilePathMapping, SourceMap}; @@ -47,50 +48,65 @@ impl<'a, 'tcx> SyntaxChecker<'a, 'tcx> { .unwrap_or(false); let buffer = buffer.borrow(); - if buffer.has_errors || is_empty { - let mut diag = if let Some(sp) = super::source_span_for_markdown_range( - self.cx.tcx, - &dox, - &code_block.range, - &item.attrs, - ) { - let (warning_message, suggest_using_text) = if buffer.has_errors { - ("could not parse code block as Rust code", true) + if !(buffer.has_errors || is_empty) { + // No errors in a non-empty program. + return; + } + + let local_id = match item.def_id.as_local() { + Some(id) => id, + // We don't need to check the syntax for other crates so returning + // without doing anything should not be a problem. + None => return, + }; + + let hir_id = self.cx.tcx.hir().local_def_id_to_hir_id(local_id); + let suggest_using_text = code_block.syntax.is_none() && code_block.is_fenced; + let is_ignore = code_block.is_ignore; + + // The span and whether it is precise or not. + let (sp, precise_span) = match super::source_span_for_markdown_range( + self.cx.tcx, + &dox, + &code_block.range, + &item.attrs, + ) { + Some(sp) => (sp, true), + None => (item.attr_span(self.cx.tcx), false), + }; + + // lambda that will use the lint to start a new diagnostic and add + // a suggestion to it when needed. + let diag_builder = |lint: LintDiagnosticBuilder<'_>| { + let mut diag = if precise_span { + let msg = if buffer.has_errors { + "could not parse code block as Rust code" } else { - ("Rust code block is empty", false) + "Rust code block is empty" }; - let mut diag = self.cx.sess().struct_span_warn(sp, warning_message); + let mut diag = lint.build(msg); + + if suggest_using_text { + let extended_msg = if is_ignore { + "`ignore` code blocks require valid Rust code for syntax highlighting. \ + Mark blocks that do not contain Rust code as text" + } else { + "mark blocks that do not contain Rust code as text" + }; - if code_block.syntax.is_none() && code_block.is_fenced { - let sp = sp.from_inner(InnerSpan::new(0, 3)); diag.span_suggestion( - sp, - "mark blocks that do not contain Rust code as text", + sp.from_inner(InnerSpan::new(0, 3)), + extended_msg, String::from("```text"), Applicability::MachineApplicable, ); - } else if suggest_using_text && code_block.is_ignore { - let sp = sp.from_inner(InnerSpan::new(0, 3)); - diag.span_suggestion( - sp, - "`ignore` code blocks require valid Rust code for syntax highlighting. \ - Mark blocks that do not contain Rust code as text", - String::from("```text,"), - Applicability::MachineApplicable, - ); } diag } else { - // We couldn't calculate the span of the markdown block that had the error, so our - // diagnostics are going to be a bit lacking. - let mut diag = self.cx.sess().struct_span_warn( - item.attr_span(self.cx.tcx), - "doc comment contains an invalid Rust code block", - ); - - if code_block.syntax.is_none() && code_block.is_fenced { + let mut diag = lint.build("doc comment contains an invalid Rust code block"); + if suggest_using_text { diag.help("mark blocks that do not contain Rust code as text: ```text"); } @@ -103,7 +119,17 @@ impl<'a, 'tcx> SyntaxChecker<'a, 'tcx> { } diag.emit(); - } + }; + + // Finally build and emit the completed diagnostic. + // All points of divergence have been handled earlier so this can be + // done the same way whether the span is precise or not. + self.cx.tcx.struct_span_lint_hir( + crate::lint::INVALID_RUST_CODEBLOCK, + hir_id, + sp, + diag_builder, + ); } } diff --git a/src/test/rustdoc-ui/ignore-block-help.stderr b/src/test/rustdoc-ui/ignore-block-help.stderr index d45cd92d2d106..313b22c4c7c20 100644 --- a/src/test/rustdoc-ui/ignore-block-help.stderr +++ b/src/test/rustdoc-ui/ignore-block-help.stderr @@ -7,11 +7,8 @@ LL | | /// let heart = '❤️'; LL | | /// ``` | |_______^ | + = note: `#[warn(invalid_rust_codeblock)]` on by default = note: error from rustc: character literal may only contain one codepoint -help: `ignore` code blocks require valid Rust code for syntax highlighting. Mark blocks that do not contain Rust code as text - | -LL | /// ```text,ignore (to-prevent-tidy-error) - | ^^^^^^^^ warning: 1 warning emitted diff --git a/src/test/rustdoc-ui/invalid-syntax.stderr b/src/test/rustdoc-ui/invalid-syntax.stderr index 75acdc5ab5f26..67e093f9de20a 100644 --- a/src/test/rustdoc-ui/invalid-syntax.stderr +++ b/src/test/rustdoc-ui/invalid-syntax.stderr @@ -7,6 +7,7 @@ LL | | /// \__________pkt->size___________/ \_result->size_/ \__pkt->si LL | | /// ``` | |_______^ | + = note: `#[warn(invalid_rust_codeblock)]` on by default = note: error from rustc: unknown start of token: \ = note: error from rustc: unknown start of token: \ = note: error from rustc: unknown start of token: \ From 04de6376bd4851879db5a2fb4783bd448b9d8021 Mon Sep 17 00:00:00 2001 From: Joshua Nelson Date: Mon, 26 Apr 2021 09:11:08 -0400 Subject: [PATCH 2/4] Add back missing help for ignore blocks This also gives a better error message when a span is missing. --- src/doc/rustdoc/src/lints.md | 2 +- .../passes/check_code_block_syntax.rs | 54 +++++++++---------- src/test/rustdoc-ui/ignore-block-help.rs | 5 +- src/test/rustdoc-ui/ignore-block-help.stderr | 7 ++- src/test/rustdoc-ui/invalid-syntax.rs | 2 +- src/test/rustdoc-ui/invalid-syntax.stderr | 4 +- 6 files changed, 40 insertions(+), 34 deletions(-) diff --git a/src/doc/rustdoc/src/lints.md b/src/doc/rustdoc/src/lints.md index 7088e60aa07da..46c4a8a41aca6 100644 --- a/src/doc/rustdoc/src/lints.md +++ b/src/doc/rustdoc/src/lints.md @@ -328,7 +328,7 @@ warning: Rust code block is empty --> src/lib.rs:8:5 | 8 | /// ```rust -| ^^^^^^^ +| ^^^^^^^ ``` ## bare_urls diff --git a/src/librustdoc/passes/check_code_block_syntax.rs b/src/librustdoc/passes/check_code_block_syntax.rs index d213a4ba52243..6d8a2b1c093f6 100644 --- a/src/librustdoc/passes/check_code_block_syntax.rs +++ b/src/librustdoc/passes/check_code_block_syntax.rs @@ -61,7 +61,7 @@ impl<'a, 'tcx> SyntaxChecker<'a, 'tcx> { }; let hir_id = self.cx.tcx.hir().local_def_id_to_hir_id(local_id); - let suggest_using_text = code_block.syntax.is_none() && code_block.is_fenced; + let empty_block = code_block.syntax.is_none() && code_block.is_fenced; let is_ignore = code_block.is_ignore; // The span and whether it is precise or not. @@ -78,40 +78,38 @@ impl<'a, 'tcx> SyntaxChecker<'a, 'tcx> { // lambda that will use the lint to start a new diagnostic and add // a suggestion to it when needed. let diag_builder = |lint: LintDiagnosticBuilder<'_>| { - let mut diag = if precise_span { - let msg = if buffer.has_errors { - "could not parse code block as Rust code" - } else { - "Rust code block is empty" - }; - - let mut diag = lint.build(msg); - - if suggest_using_text { - let extended_msg = if is_ignore { - "`ignore` code blocks require valid Rust code for syntax highlighting. \ - Mark blocks that do not contain Rust code as text" - } else { - "mark blocks that do not contain Rust code as text" - }; + let explanation = if is_ignore { + "`ignore` code blocks require valid Rust code for syntax highlighting; \ + mark blocks that do not contain Rust code as text" + } else { + "mark blocks that do not contain Rust code as text" + }; + let msg = if buffer.has_errors { + "could not parse code block as Rust code" + } else { + "Rust code block is empty" + }; + let mut diag = lint.build(msg); + if precise_span { + if is_ignore { + // giving an accurate suggestion is hard because `ignore` might not have come first in the list. + // just give a `help` instead. + diag.span_help( + sp.from_inner(InnerSpan::new(0, 3)), + &format!("{}: ```text", explanation), + ); + } else if empty_block { diag.span_suggestion( sp.from_inner(InnerSpan::new(0, 3)), - extended_msg, + explanation, String::from("```text"), Applicability::MachineApplicable, ); } - - diag - } else { - let mut diag = lint.build("doc comment contains an invalid Rust code block"); - if suggest_using_text { - diag.help("mark blocks that do not contain Rust code as text: ```text"); - } - - diag - }; + } else if empty_block || is_ignore { + diag.help(&format!("{}: ```text", explanation)); + } // FIXME(#67563): Provide more context for these errors by displaying the spans inline. for message in buffer.messages.iter() { diff --git a/src/test/rustdoc-ui/ignore-block-help.rs b/src/test/rustdoc-ui/ignore-block-help.rs index c22dddd11dffa..86f6a2868fb56 100644 --- a/src/test/rustdoc-ui/ignore-block-help.rs +++ b/src/test/rustdoc-ui/ignore-block-help.rs @@ -3,5 +3,8 @@ /// ```ignore (to-prevent-tidy-error) /// let heart = '❤️'; /// ``` -//~^^^ WARN +//~^^^ WARNING could not parse code block +//~| NOTE on by default +//~| NOTE character literal may only contain one codepoint +//~| HELP `ignore` code blocks require valid Rust code pub struct X; diff --git a/src/test/rustdoc-ui/ignore-block-help.stderr b/src/test/rustdoc-ui/ignore-block-help.stderr index 313b22c4c7c20..b809ece86e76a 100644 --- a/src/test/rustdoc-ui/ignore-block-help.stderr +++ b/src/test/rustdoc-ui/ignore-block-help.stderr @@ -7,7 +7,12 @@ LL | | /// let heart = '❤️'; LL | | /// ``` | |_______^ | - = note: `#[warn(invalid_rust_codeblock)]` on by default + = note: `#[warn(rustdoc::invalid_rust_codeblock)]` on by default +help: `ignore` code blocks require valid Rust code for syntax highlighting; mark blocks that do not contain Rust code as text: ```text + --> $DIR/ignore-block-help.rs:3:5 + | +LL | /// ```ignore (to-prevent-tidy-error) + | ^^^ = note: error from rustc: character literal may only contain one codepoint warning: 1 warning emitted diff --git a/src/test/rustdoc-ui/invalid-syntax.rs b/src/test/rustdoc-ui/invalid-syntax.rs index c395a8ef3d41a..b503d1093fda8 100644 --- a/src/test/rustdoc-ui/invalid-syntax.rs +++ b/src/test/rustdoc-ui/invalid-syntax.rs @@ -71,7 +71,7 @@ pub fn blargh() {} /// \_ #[doc = "```"] pub fn crazy_attrs() {} -//~^^^^ WARNING doc comment contains an invalid Rust code block +//~^^^^ WARNING could not parse code block /// ```rust /// ``` diff --git a/src/test/rustdoc-ui/invalid-syntax.stderr b/src/test/rustdoc-ui/invalid-syntax.stderr index 67e093f9de20a..7fcb9a0e9a9ab 100644 --- a/src/test/rustdoc-ui/invalid-syntax.stderr +++ b/src/test/rustdoc-ui/invalid-syntax.stderr @@ -7,7 +7,7 @@ LL | | /// \__________pkt->size___________/ \_result->size_/ \__pkt->si LL | | /// ``` | |_______^ | - = note: `#[warn(invalid_rust_codeblock)]` on by default + = note: `#[warn(rustdoc::invalid_rust_codeblock)]` on by default = note: error from rustc: unknown start of token: \ = note: error from rustc: unknown start of token: \ = note: error from rustc: unknown start of token: \ @@ -91,7 +91,7 @@ LL | | /// ``` | = note: error from rustc: unknown start of token: \ -warning: doc comment contains an invalid Rust code block +warning: could not parse code block as Rust code --> $DIR/invalid-syntax.rs:70:1 | LL | / #[doc = "```"] From b92723b522f9ead35fd70ffcade9be996b3fc762 Mon Sep 17 00:00:00 2001 From: Joshua Nelson Date: Fri, 30 Apr 2021 21:28:32 -0400 Subject: [PATCH 3/4] Rename INVALID_RUST_CODEBLOCK{,S} --- src/doc/rustdoc/src/lints.md | 4 ++-- src/librustdoc/lint.rs | 8 ++++---- src/librustdoc/passes/check_code_block_syntax.rs | 2 +- src/test/rustdoc-ui/ignore-block-help.stderr | 2 +- src/test/rustdoc-ui/invalid-syntax.stderr | 2 +- 5 files changed, 9 insertions(+), 9 deletions(-) diff --git a/src/doc/rustdoc/src/lints.md b/src/doc/rustdoc/src/lints.md index 46c4a8a41aca6..9f1e1a5b88b2f 100644 --- a/src/doc/rustdoc/src/lints.md +++ b/src/doc/rustdoc/src/lints.md @@ -294,7 +294,7 @@ warning: unclosed HTML tag `h1` warning: 2 warnings emitted ``` -## invalid_rust_codeblock +## invalid_rust_codeblocks This lint **warns by default**. It detects Rust code blocks in documentation examples that are invalid (e.g. empty, not parsable as Rust). For example: @@ -322,7 +322,7 @@ warning: Rust code block is empty 4 | | /// ``` | |_______^ | -= note: `#[warn(rustdoc::invalid_rust_codeblock)]` on by default += note: `#[warn(rustdoc::invalid_rust_codeblocks)]` on by default warning: Rust code block is empty --> src/lib.rs:8:5 diff --git a/src/librustdoc/lint.rs b/src/librustdoc/lint.rs index 597efed56e176..376c83b1a6ea8 100644 --- a/src/librustdoc/lint.rs +++ b/src/librustdoc/lint.rs @@ -158,13 +158,13 @@ declare_rustdoc_lint! { } declare_rustdoc_lint! { - /// The `invalid_rust_codeblock` lint detects Rust code blocks in + /// The `invalid_rust_codeblocks` lint detects Rust code blocks in /// documentation examples that are invalid (e.g. empty, not parsable as /// Rust code). This is a `rustdoc` only lint, see the documentation in the /// [rustdoc book]. /// - /// [rustdoc book]: ../../../rustdoc/lints.html#invalid_rust_codeblock - INVALID_RUST_CODEBLOCK, + /// [rustdoc book]: ../../../rustdoc/lints.html#invalid_rust_codeblocks + INVALID_RUST_CODEBLOCKS, Warn, "codeblock could not be parsed as valid Rust or is empty" } @@ -176,7 +176,7 @@ crate static RUSTDOC_LINTS: Lazy> = Lazy::new(|| { MISSING_DOC_CODE_EXAMPLES, PRIVATE_DOC_TESTS, INVALID_CODEBLOCK_ATTRIBUTES, - INVALID_RUST_CODEBLOCK, + INVALID_RUST_CODEBLOCKS, INVALID_HTML_TAGS, BARE_URLS, MISSING_CRATE_LEVEL_DOCS, diff --git a/src/librustdoc/passes/check_code_block_syntax.rs b/src/librustdoc/passes/check_code_block_syntax.rs index 6d8a2b1c093f6..394a26201246f 100644 --- a/src/librustdoc/passes/check_code_block_syntax.rs +++ b/src/librustdoc/passes/check_code_block_syntax.rs @@ -123,7 +123,7 @@ impl<'a, 'tcx> SyntaxChecker<'a, 'tcx> { // All points of divergence have been handled earlier so this can be // done the same way whether the span is precise or not. self.cx.tcx.struct_span_lint_hir( - crate::lint::INVALID_RUST_CODEBLOCK, + crate::lint::INVALID_RUST_CODEBLOCKS, hir_id, sp, diag_builder, diff --git a/src/test/rustdoc-ui/ignore-block-help.stderr b/src/test/rustdoc-ui/ignore-block-help.stderr index b809ece86e76a..9c02ff11d19c4 100644 --- a/src/test/rustdoc-ui/ignore-block-help.stderr +++ b/src/test/rustdoc-ui/ignore-block-help.stderr @@ -7,7 +7,7 @@ LL | | /// let heart = '❤️'; LL | | /// ``` | |_______^ | - = note: `#[warn(rustdoc::invalid_rust_codeblock)]` on by default + = note: `#[warn(rustdoc::invalid_rust_codeblocks)]` on by default help: `ignore` code blocks require valid Rust code for syntax highlighting; mark blocks that do not contain Rust code as text: ```text --> $DIR/ignore-block-help.rs:3:5 | diff --git a/src/test/rustdoc-ui/invalid-syntax.stderr b/src/test/rustdoc-ui/invalid-syntax.stderr index 7fcb9a0e9a9ab..82eac9bd68b21 100644 --- a/src/test/rustdoc-ui/invalid-syntax.stderr +++ b/src/test/rustdoc-ui/invalid-syntax.stderr @@ -7,7 +7,7 @@ LL | | /// \__________pkt->size___________/ \_result->size_/ \__pkt->si LL | | /// ``` | |_______^ | - = note: `#[warn(rustdoc::invalid_rust_codeblock)]` on by default + = note: `#[warn(rustdoc::invalid_rust_codeblocks)]` on by default = note: error from rustc: unknown start of token: \ = note: error from rustc: unknown start of token: \ = note: error from rustc: unknown start of token: \ From 0511ba4ed419599d9b099547f9db3c9d01713e64 Mon Sep 17 00:00:00 2001 From: Joshua Nelson Date: Mon, 3 May 2021 22:19:49 -0400 Subject: [PATCH 4/4] Address review comments - Simplify boolean expression - Give an example of invalid syntax - Remove explanation of why code block is text --- .../src/borrow_check/region_infer/mod.rs | 2 +- src/doc/rustdoc/src/lints.md | 33 +++++++++++-------- .../passes/check_code_block_syntax.rs | 2 +- 3 files changed, 22 insertions(+), 15 deletions(-) diff --git a/compiler/rustc_mir/src/borrow_check/region_infer/mod.rs b/compiler/rustc_mir/src/borrow_check/region_infer/mod.rs index 9dc2e3d292359..f4d78ac04cb02 100644 --- a/compiler/rustc_mir/src/borrow_check/region_infer/mod.rs +++ b/compiler/rustc_mir/src/borrow_check/region_infer/mod.rs @@ -1241,7 +1241,7 @@ impl<'tcx> RegionInferenceContext<'tcx> { /// it. However, it works pretty well in practice. In particular, /// this is needed to deal with projection outlives bounds like /// - /// ```text (internal compiler representation so lifetime syntax is invalid) + /// ```text /// >::Item: '1 /// ``` /// diff --git a/src/doc/rustdoc/src/lints.md b/src/doc/rustdoc/src/lints.md index 9f1e1a5b88b2f..16b091eb255b0 100644 --- a/src/doc/rustdoc/src/lints.md +++ b/src/doc/rustdoc/src/lints.md @@ -305,30 +305,37 @@ examples that are invalid (e.g. empty, not parsable as Rust). For example: /// ```rust /// ``` /// -/// Unclosed code blocks (with and without the `rust` marker): +/// Invalid syntax in code blocks: /// /// ```rust -fn main() {} +/// '< +/// ``` +pub fn foo() {} ``` Which will give: ```text warning: Rust code block is empty ---> src/lib.rs:3:5 -| + --> lint.rs:3:5 + | 3 | /// ```rust -| _____^ + | _____^ 4 | | /// ``` -| |_______^ -| -= note: `#[warn(rustdoc::invalid_rust_codeblocks)]` on by default + | |_______^ + | + = note: `#[warn(rustdoc::invalid_rust_codeblocks)]` on by default -warning: Rust code block is empty ---> src/lib.rs:8:5 -| -8 | /// ```rust -| ^^^^^^^ +warning: could not parse code block as Rust code + --> lint.rs:8:5 + | +8 | /// ```rust + | _____^ +9 | | /// '< +10 | | /// ``` + | |_______^ + | + = note: error from rustc: unterminated character literal ``` ## bare_urls diff --git a/src/librustdoc/passes/check_code_block_syntax.rs b/src/librustdoc/passes/check_code_block_syntax.rs index 394a26201246f..74d396efd575d 100644 --- a/src/librustdoc/passes/check_code_block_syntax.rs +++ b/src/librustdoc/passes/check_code_block_syntax.rs @@ -48,7 +48,7 @@ impl<'a, 'tcx> SyntaxChecker<'a, 'tcx> { .unwrap_or(false); let buffer = buffer.borrow(); - if !(buffer.has_errors || is_empty) { + if !buffer.has_errors && !is_empty { // No errors in a non-empty program. return; }