Unbalanced tick marks lead to confusing/inverted error messages from clippy::doc-markdown

[jgallagher-cs]

The title of the issue spoils the fun a bit, but I'll lead with the confusing error message a teammate ran into yesterday:

warning: you should put `encompassed_by` between ticks in the documentation
 --> src/main.rs:2:16
  |
2 | /// should be `encompassed_by` tick marks because they `contain_underscores`.
  |                ^^^^^^^^^^^^^^
  |
  = note: `-W clippy::doc-markdown` implied by `-W clippy::pedantic`
  = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#doc_markdown

warning: you should put `contain_underscores` between ticks in the documentation
 --> src/main.rs:2:57
  |
2 | /// should be `encompassed_by` tick marks because they `contain_underscores`.
  |                                                         ^^^^^^^^^^^^^^^^^^^
  |
  = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#doc_markdown

warning: you should put `unbalanced_tick` between ticks in the documentation
 --> src/main.rs:3:29
  |
3 | /// Because of the initial `unbalanced_tick` pair, the error message is
  |                             ^^^^^^^^^^^^^^^
  |
  = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#doc_markdown

warning: you should put `confusing_and_misleading` between ticks in the documentation
 --> src/main.rs:4:11
  |
4 | /// very `confusing_and_misleading`.
  |           ^^^^^^^^^^^^^^^^^^^^^^^^
  |
  = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#doc_markdown

warning: 4 warnings emitted

The doc comment that produces these odd warnings:

/// This is a doc comment with `unbalanced_tick marks and several words that
/// should be `encompassed_by` tick marks because they `contain_underscores`.
/// Because of the initial `unbalanced_tick` pair, the error message is
/// very `confusing_and_misleading`.
pub fn testing() {}

unbalanced_tick on the first line is missing its closing tick mark, which causes the "tick-mark-ness" of the remainder of the comment to be inverted. So technically all of the warnings are correct: encompassed_by is not inside tick marks (because the tick mark that appears to be at the beginning of encompassed_by is actually closing the tick mark from the first line, and the tick mark that appears to be at the ending of encompassed_by is actually opening a new tick mark section). However, they're very confusing! :)

[ebobrow]

@rustbot claim