Auto merge of #8011 - birkenfeld:double_backticks, r=xFrednet

Avoid inline hints with double backticks for `doc-markdown`

The easiest route here was to ensure that the suggestion is always shown on
its own line, where no additional backticks are added by the diagnostic formatter.

Fixes #8002

---

*Please write a short comment explaining your change (or "none" for internal only changes)*

changelog: Avoid inline hints with double backticks for `doc-markdown`

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