From 0c4055c28353856bcc3cd22d77d1d89359d1825b Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sat, 20 Nov 2021 18:13:24 +0100 Subject: [PATCH] Avoid inline hints with double backticks for `doc-markdown` --- clippy_lints/src/doc.rs | 21 ++- tests/ui/doc/doc-fixable.stderr | 209 +++++++++++++++++++++++---- tests/ui/doc/unbalanced_ticks.stderr | 21 ++- 3 files changed, 212 insertions(+), 39 deletions(-) diff --git a/clippy_lints/src/doc.rs b/clippy_lints/src/doc.rs index c1ce851a67d..2cdd59c5691 100644 --- a/clippy_lints/src/doc.rs +++ b/clippy_lints/src/doc.rs @@ -1,5 +1,5 @@ use clippy_utils::attrs::is_doc_hidden; -use clippy_utils::diagnostics::{span_lint, span_lint_and_help, span_lint_and_note, span_lint_and_sugg}; +use clippy_utils::diagnostics::{span_lint, span_lint_and_help, span_lint_and_note, span_lint_and_then}; use clippy_utils::source::{first_line_of_span, snippet_with_applicability}; use clippy_utils::ty::{implements_trait, is_type_diagnostic_item}; use clippy_utils::{is_entrypoint_fn, is_expn_of, match_panic_def_id, method_chain_args, return_ty}; @@ -10,7 +10,7 @@ use rustc_ast::token::CommentKind; use rustc_data_structures::fx::FxHashSet; use rustc_data_structures::sync::Lrc; use rustc_errors::emitter::EmitterWriter; -use rustc_errors::{Applicability, Handler}; +use rustc_errors::{Applicability, Handler, SuggestionStyle}; use rustc_hir as hir; use rustc_hir::intravisit::{self, NestedVisitorMap, Visitor}; use rustc_hir::{AnonConst, Expr, ExprKind, QPath}; @@ -770,14 +770,23 @@ fn check_word(cx: &LateContext<'_>, word: &str, span: Span) { if has_underscore(word) || word.contains("::") || is_camel_case(word) { let mut applicability = Applicability::MachineApplicable; - span_lint_and_sugg( + span_lint_and_then( cx, DOC_MARKDOWN, span, "item in documentation is missing backticks", - "try", - format!("`{}`", snippet_with_applicability(cx, span, "..", &mut applicability)), - applicability, + |diag| { + let snippet = snippet_with_applicability(cx, span, "..", &mut applicability); + diag.span_suggestion_with_style( + span, + "try", + format!("`{}`", snippet), + applicability, + // always show the suggestion in a separate line, since the + // inline presentation adds another pair of backticks + SuggestionStyle::ShowAlways, + ); + }, ); } } diff --git a/tests/ui/doc/doc-fixable.stderr b/tests/ui/doc/doc-fixable.stderr index 31132f86edb..40345370c04 100644 --- a/tests/ui/doc/doc-fixable.stderr +++ b/tests/ui/doc/doc-fixable.stderr @@ -2,183 +2,332 @@ error: item in documentation is missing backticks --> $DIR/doc-fixable.rs:9:9 | LL | /// The foo_bar function does _nothing_. See also foo::bar. (note the dot there) - | ^^^^^^^ help: try: ``foo_bar`` + | ^^^^^^^ | = note: `-D clippy::doc-markdown` implied by `-D warnings` +help: try + | +LL | /// The `foo_bar` function does _nothing_. See also foo::bar. (note the dot there) + | ~~~~~~~~~ error: item in documentation is missing backticks --> $DIR/doc-fixable.rs:9:51 | LL | /// The foo_bar function does _nothing_. See also foo::bar. (note the dot there) - | ^^^^^^^^ help: try: ``foo::bar`` + | ^^^^^^^^ + | +help: try + | +LL | /// The foo_bar function does _nothing_. See also `foo::bar`. (note the dot there) + | ~~~~~~~~~~ error: item in documentation is missing backticks --> $DIR/doc-fixable.rs:10:83 | LL | /// Markdown is _weird_. I mean _really weird_. This /_ is ok. So is `_`. But not Foo::some_fun - | ^^^^^^^^^^^^^ help: try: ``Foo::some_fun`` + | ^^^^^^^^^^^^^ + | +help: try + | +LL | /// Markdown is _weird_. I mean _really weird_. This /_ is ok. So is `_`. But not `Foo::some_fun` + | ~~~~~~~~~~~~~~~ error: item in documentation is missing backticks --> $DIR/doc-fixable.rs:12:13 | LL | /// Here be ::a::global:path, and _::another::global::path_. :: is not a path though. - | ^^^^^^^^^^^^^^^^ help: try: ``::a::global:path`` + | ^^^^^^^^^^^^^^^^ + | +help: try + | +LL | /// Here be `::a::global:path`, and _::another::global::path_. :: is not a path though. + | ~~~~~~~~~~~~~~~~~~ error: item in documentation is missing backticks --> $DIR/doc-fixable.rs:12:36 | LL | /// Here be ::a::global:path, and _::another::global::path_. :: is not a path though. - | ^^^^^^^^^^^^^^^^^^^^^^^ help: try: ``::another::global::path`` + | ^^^^^^^^^^^^^^^^^^^^^^^ + | +help: try + | +LL | /// Here be ::a::global:path, and _`::another::global::path`_. :: is not a path though. + | ~~~~~~~~~~~~~~~~~~~~~~~~~ error: item in documentation is missing backticks --> $DIR/doc-fixable.rs:13:25 | LL | /// Import an item from ::awesome::global::blob:: (Intended postfix) - | ^^^^^^^^^^^^^^^^^^^^^^^^^ help: try: ``::awesome::global::blob::`` + | ^^^^^^^^^^^^^^^^^^^^^^^^^ + | +help: try + | +LL | /// Import an item from `::awesome::global::blob::` (Intended postfix) + | ~~~~~~~~~~~~~~~~~~~~~~~~~~~ error: item in documentation is missing backticks --> $DIR/doc-fixable.rs:14:31 | LL | /// These are the options for ::Cat: (Intended trailing single colon, shouldn't be linted) - | ^^^^^ help: try: ``::Cat`` + | ^^^^^ + | +help: try + | +LL | /// These are the options for `::Cat`: (Intended trailing single colon, shouldn't be linted) + | ~~~~~~~ error: item in documentation is missing backticks --> $DIR/doc-fixable.rs:15:22 | LL | /// That's not code ~NotInCodeBlock~. - | ^^^^^^^^^^^^^^ help: try: ``NotInCodeBlock`` + | ^^^^^^^^^^^^^^ + | +help: try + | +LL | /// That's not code ~`NotInCodeBlock`~. + | ~~~~~~~~~~~~~~~~ error: item in documentation is missing backticks --> $DIR/doc-fixable.rs:16:5 | LL | /// be_sure_we_got_to_the_end_of_it - | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ help: try: ``be_sure_we_got_to_the_end_of_it`` + | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + | +help: try + | +LL | /// `be_sure_we_got_to_the_end_of_it` + | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ error: item in documentation is missing backticks --> $DIR/doc-fixable.rs:30:5 | LL | /// be_sure_we_got_to_the_end_of_it - | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ help: try: ``be_sure_we_got_to_the_end_of_it`` + | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + | +help: try + | +LL | /// `be_sure_we_got_to_the_end_of_it` + | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ error: item in documentation is missing backticks --> $DIR/doc-fixable.rs:37:5 | LL | /// be_sure_we_got_to_the_end_of_it - | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ help: try: ``be_sure_we_got_to_the_end_of_it`` + | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + | +help: try + | +LL | /// `be_sure_we_got_to_the_end_of_it` + | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ error: item in documentation is missing backticks --> $DIR/doc-fixable.rs:51:5 | LL | /// be_sure_we_got_to_the_end_of_it - | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ help: try: ``be_sure_we_got_to_the_end_of_it`` + | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + | +help: try + | +LL | /// `be_sure_we_got_to_the_end_of_it` + | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ error: item in documentation is missing backticks --> $DIR/doc-fixable.rs:74:5 | LL | /// be_sure_we_got_to_the_end_of_it - | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ help: try: ``be_sure_we_got_to_the_end_of_it`` + | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + | +help: try + | +LL | /// `be_sure_we_got_to_the_end_of_it` + | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ error: item in documentation is missing backticks --> $DIR/doc-fixable.rs:78:22 | LL | /// This test has [a link_with_underscores][chunked-example] inside it. See #823. - | ^^^^^^^^^^^^^^^^^^^^^ help: try: ``link_with_underscores`` + | ^^^^^^^^^^^^^^^^^^^^^ + | +help: try + | +LL | /// This test has [a `link_with_underscores`][chunked-example] inside it. See #823. + | ~~~~~~~~~~~~~~~~~~~~~~~ error: item in documentation is missing backticks --> $DIR/doc-fixable.rs:81:21 | LL | /// It can also be [inline_link2]. - | ^^^^^^^^^^^^ help: try: ``inline_link2`` + | ^^^^^^^^^^^^ + | +help: try + | +LL | /// It can also be [`inline_link2`]. + | ~~~~~~~~~~~~~~ error: item in documentation is missing backticks --> $DIR/doc-fixable.rs:91:5 | LL | /// be_sure_we_got_to_the_end_of_it - | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ help: try: ``be_sure_we_got_to_the_end_of_it`` + | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + | +help: try + | +LL | /// `be_sure_we_got_to_the_end_of_it` + | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ error: item in documentation is missing backticks --> $DIR/doc-fixable.rs:99:8 | LL | /// ## CamelCaseThing - | ^^^^^^^^^^^^^^ help: try: ``CamelCaseThing`` + | ^^^^^^^^^^^^^^ + | +help: try + | +LL | /// ## `CamelCaseThing` + | ~~~~~~~~~~~~~~~~ error: item in documentation is missing backticks --> $DIR/doc-fixable.rs:102:7 | LL | /// # CamelCaseThing - | ^^^^^^^^^^^^^^ help: try: ``CamelCaseThing`` + | ^^^^^^^^^^^^^^ + | +help: try + | +LL | /// # `CamelCaseThing` + | ~~~~~~~~~~~~~~~~ error: item in documentation is missing backticks --> $DIR/doc-fixable.rs:104:22 | LL | /// Not a title #897 CamelCaseThing - | ^^^^^^^^^^^^^^ help: try: ``CamelCaseThing`` + | ^^^^^^^^^^^^^^ + | +help: try + | +LL | /// Not a title #897 `CamelCaseThing` + | ~~~~~~~~~~~~~~~~ error: item in documentation is missing backticks --> $DIR/doc-fixable.rs:105:5 | LL | /// be_sure_we_got_to_the_end_of_it - | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ help: try: ``be_sure_we_got_to_the_end_of_it`` + | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + | +help: try + | +LL | /// `be_sure_we_got_to_the_end_of_it` + | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ error: item in documentation is missing backticks --> $DIR/doc-fixable.rs:112:5 | LL | /// be_sure_we_got_to_the_end_of_it - | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ help: try: ``be_sure_we_got_to_the_end_of_it`` + | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + | +help: try + | +LL | /// `be_sure_we_got_to_the_end_of_it` + | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ error: item in documentation is missing backticks --> $DIR/doc-fixable.rs:125:5 | LL | /// be_sure_we_got_to_the_end_of_it - | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ help: try: ``be_sure_we_got_to_the_end_of_it`` + | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + | +help: try + | +LL | /// `be_sure_we_got_to_the_end_of_it` + | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ error: item in documentation is missing backticks --> $DIR/doc-fixable.rs:136:43 | LL | /** E.g., serialization of an empty list: FooBar - | ^^^^^^ help: try: ``FooBar`` + | ^^^^^^ + | +help: try + | +LL | /** E.g., serialization of an empty list: `FooBar` + | ~~~~~~~~ error: item in documentation is missing backticks --> $DIR/doc-fixable.rs:141:5 | LL | And BarQuz too. - | ^^^^^^ help: try: ``BarQuz`` + | ^^^^^^ + | +help: try + | +LL | And `BarQuz` too. + | ~~~~~~~~ error: item in documentation is missing backticks --> $DIR/doc-fixable.rs:142:1 | LL | be_sure_we_got_to_the_end_of_it - | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ help: try: ``be_sure_we_got_to_the_end_of_it`` + | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + | +help: try + | +LL | `be_sure_we_got_to_the_end_of_it` + | error: item in documentation is missing backticks --> $DIR/doc-fixable.rs:147:43 | LL | /** E.g., serialization of an empty list: FooBar - | ^^^^^^ help: try: ``FooBar`` + | ^^^^^^ + | +help: try + | +LL | /** E.g., serialization of an empty list: `FooBar` + | ~~~~~~~~ error: item in documentation is missing backticks --> $DIR/doc-fixable.rs:152:5 | LL | And BarQuz too. - | ^^^^^^ help: try: ``BarQuz`` + | ^^^^^^ + | +help: try + | +LL | And `BarQuz` too. + | ~~~~~~~~ error: item in documentation is missing backticks --> $DIR/doc-fixable.rs:153:1 | LL | be_sure_we_got_to_the_end_of_it - | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ help: try: ``be_sure_we_got_to_the_end_of_it`` + | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + | +help: try + | +LL | `be_sure_we_got_to_the_end_of_it` + | error: item in documentation is missing backticks --> $DIR/doc-fixable.rs:164:5 | LL | /// be_sure_we_got_to_the_end_of_it - | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ help: try: ``be_sure_we_got_to_the_end_of_it`` + | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + | +help: try + | +LL | /// `be_sure_we_got_to_the_end_of_it` + | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ error: item in documentation is missing backticks --> $DIR/doc-fixable.rs:183:22 | LL | /// An iterator over mycrate::Collection's values. - | ^^^^^^^^^^^^^^^^^^^ help: try: ``mycrate::Collection`` + | ^^^^^^^^^^^^^^^^^^^ + | +help: try + | +LL | /// An iterator over `mycrate::Collection`'s values. + | ~~~~~~~~~~~~~~~~~~~~~ error: aborting due to 30 previous errors diff --git a/tests/ui/doc/unbalanced_ticks.stderr b/tests/ui/doc/unbalanced_ticks.stderr index 9670e5c24fb..a462b98871a 100644 --- a/tests/ui/doc/unbalanced_ticks.stderr +++ b/tests/ui/doc/unbalanced_ticks.stderr @@ -22,7 +22,12 @@ error: item in documentation is missing backticks --> $DIR/unbalanced_ticks.rs:15:32 | LL | /// This paragraph is fine and should_be linted normally. - | ^^^^^^^^^ help: try: ``should_be`` + | ^^^^^^^^^ + | +help: try + | +LL | /// This paragraph is fine and `should_be` linted normally. + | ~~~~~~~~~~~ error: backticks are unbalanced --> $DIR/unbalanced_ticks.rs:17:1 @@ -36,7 +41,12 @@ error: item in documentation is missing backticks --> $DIR/unbalanced_ticks.rs:30:8 | LL | /// ## not_fine - | ^^^^^^^^ help: try: ``not_fine`` + | ^^^^^^^^ + | +help: try + | +LL | /// ## `not_fine` + | ~~~~~~~~~~ error: backticks are unbalanced --> $DIR/unbalanced_ticks.rs:32:1 @@ -58,7 +68,12 @@ error: item in documentation is missing backticks --> $DIR/unbalanced_ticks.rs:35:23 | LL | /// - This item needs backticks_here - | ^^^^^^^^^^^^^^ help: try: ``backticks_here`` + | ^^^^^^^^^^^^^^ + | +help: try + | +LL | /// - This item needs `backticks_here` + | ~~~~~~~~~~~~~~~~ error: aborting due to 8 previous errors