src/docs/doc_markdown.txt

   1 ### What it does
   2 Checks for the presence of `_`, `::` or camel-case words
   3 outside ticks in documentation.
   4
   5 ### Why is this bad?
   6 *Rustdoc* supports markdown formatting, `_`, `::` and
   7 camel-case probably indicates some code which should be included between
   8 ticks. `_` can also be used for emphasis in markdown, this lint tries to
   9 consider that.
  10
  11 ### Known problems
  12 Lots of bad docs won’t be fixed, what the lint checks
  13 for is limited, and there are still false positives. HTML elements and their
  14 content are not linted.
  15
  16 In addition, when writing documentation comments, including `[]` brackets
  17 inside a link text would trip the parser. Therefore, documenting link with
  18 `[`SmallVec<[T; INLINE_CAPACITY]>`]` and then [`SmallVec<[T; INLINE_CAPACITY]>`]: SmallVec
  19 would fail.
  20
  21 ### Examples
  22 ```
  23 /// Do something with the foo_bar parameter. See also
  24 /// that::other::module::foo.
  25 // ^ `foo_bar` and `that::other::module::foo` should be ticked.
  26 fn doit(foo_bar: usize) {}
  27 ```
  28
  29 ```
  30 // Link text with `[]` brackets should be written as following:
  31 /// Consume the array and return the inner
  32 /// [`SmallVec<[T; INLINE_CAPACITY]>`][SmallVec].
  33 /// [SmallVec]: SmallVec
  34 fn main() {}
  35 ```