rustdoc: Add a new lint for broken inline code
This patch adds `rustdoc::unescaped_backticks`, a new rustdoc lint that will detect broken inline code nodes.
The lint woks by finding stray backticks and with some heuristics tries to guess where the second backtick might be missing.
Here is how it looks:
```rust
#![warn(rustdoc::unescaped_backticks)]
/// `add(a, b) is the same as `add(b, a)`.
pub fn add(a: i32, b: i32) -> i32 { a + b }
```
```text
warning: unescaped backtick
--> src/lib.rs:3:41
|
3 | /// `add(a, b) is the same as `add(b, a)`.
| ^
|
help: a previous inline code might be longer than expected
|
3 | /// `add(a, b)` is the same as `add(b, a)`.
| +
help: if you meant to use a literal backtick, escape it
|
3 | /// `add(a, b) is the same as `add(b, a)\`.
| +
```
If we can't get proper spans, for example if the doc comment comes from a macro expansion, we print the suggestion in help messages instead. Here's a [real-world example](https://docs.rs/tracing-subscriber/0.3.17/tracing_subscriber/layer/trait.Filter.html#method.max_level_hint):
```text
warning: unescaped backtick
--> /tracing-subscriber-0.3.17/src/layer/mod.rs:1400:9
|
1400 | / /// Returns an optional hint of the highest [verbosity level][level] that
1401 | | /// this `Filter` will enable.
1402 | | ///
1403 | | /// If this method returns a [`LevelFilter`], it will be used as a hint to
... |
1427 | | /// [`Interest`]: tracing_core::subscriber::Interest
1428 | | /// [rebuild]: tracing_core::callsite::rebuild_interest_cache
| |_____________________________________________________________________^
|
= help: a previous inline code might be longer than expected
change: Therefore, if the `Filter will change the value returned by this
to this: Therefore, if the `Filter` will change the value returned by this
= help: if you meant to use a literal backtick, escape it
change: [`rebuild_interest_cache`][rebuild] is called after the value of the max
to this: [`rebuild_interest_cache\`][rebuild] is called after the value of the max
```
You can find more examples [here](https://gist.github.com/lukas-code/7678ddf5c608aee97b3a669de80d3465).
A limitation of the current implementation is, that it cannot suggest removing misplaced backticks, for example [here](https://docs.rs/tikv-jemalloc-sys/0.5.3+5.3.0-patched/tikv_jemalloc_sys/fn.mallctl.html).
The lint is allowed by default ~~and nightly-only~~ for now, ~~but without a feature gate. This is similar to how `rustdoc::invalid_html_tags` and `rustdoc::bare_urls` were handled.~~
825bc606f5