doc_markdown: suggestion looks like double backticks needed

[birkenfeld]

For example:

error: item in documentation is missing backticks
   --> src/tcp.rs:135:58
    |
135 |     /// closed immediately.  The route can be added from TwinCAT, or this
    |                                                          ^^^^^^^ help: try: ``TwinCAT``
    |
    = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#doc_markdown

Since all "try" hints are already enclosed in backticks, we end up with double backticks in the suggestion, which looks like it could be actual markup (especially if you also use ReST).

I suggest to omit the backticks in the hint, leading to try: `TwinCAT` which together with the error text makes it obvious what is meant.

[xFrednet]

Hey, the suggestion intentionally has two backticks to make the fix automatically applicable. Clippy suggests writing `TwinCAT` and rustc automatically adds the outer backtick. Maybe this could be improved by showing the suggestion with a single backtick in a help message, and then using span_suggestion_hidden() to suggest the update with backticks. This would make the message a bit cleaner.

@rustbot label -C-bug +C-enhancement +good-first-issue

[birkenfeld]

Thanks for the explanation, that makes sense.

I can try to do what you suggested. Is there a facility to test the automated update suggestions in addition to the compiler output uitests?

[xFrednet]

Sure, that would be wonderful. The lint is currently emitted here:

rust-clippy/clippy_lints/src/doc.rs

Lines 773 to 781 in 827fd50

	span_lint_and_sugg(
	cx,
	DOC_MARKDOWN,
	span,
	"item in documentation is missing backticks",
	"try",
	format!("`{}`", snippet_with_applicability(cx, span, "..", &mut applicability)),
	applicability,
	);

The span_lint_and_sugg would need to be replaced with an span_lint_and_then function. Clippy's uitest save the lint messages in an .stderr file and create a .fixed file where the suggestions are applied. The lint already has some test files for these cases. See: #7904

You can claim the issue by commenting @rustbot claim. Let me know if you have any questions 🙃