1 files changed, 35 insertions, 0 deletions
diff --git a/src/tools/clippy/src/docs/doc_markdown.txt b/src/tools/clippy/src/docs/doc_markdown.txt
new file mode 100644
index 000000000..94f54c587
--- /dev/null
+++ b/src/tools/clippy/src/docs/doc_markdown.txt
@@ -0,0 +1,35 @@
+### What it does
+Checks for the presence of `_`, `::` or camel-case words
+outside ticks in documentation.
+
+### Why is this bad?
+*Rustdoc* supports markdown formatting, `_`, `::` and
+camel-case probably indicates some code which should be included between
+ticks. `_` can also be used for emphasis in markdown, this lint tries to
+consider that.
+
+### Known problems
+Lots of bad docs won’t be fixed, what the lint checks
+for is limited, and there are still false positives. HTML elements and their
+content are not linted.
+
+In addition, when writing documentation comments, including `[]` brackets
+inside a link text would trip the parser. Therefore, documenting link with
+`[`SmallVec<[T; INLINE_CAPACITY]>`]` and then [`SmallVec<[T; INLINE_CAPACITY]>`]: SmallVec
+would fail.
+
+### Examples
+```
+/// Do something with the foo_bar parameter. See also
+/// that::other::module::foo.
+// ^ `foo_bar` and `that::other::module::foo` should be ticked.
+fn doit(foo_bar: usize) {}
+```
+
+```
+// Link text with `[]` brackets should be written as following:
+/// Consume the array and return the inner
+/// [`SmallVec<[T; INLINE_CAPACITY]>`][SmallVec].
+/// [SmallVec]: SmallVec
+fn main() {}
+```
+\ No newline at end of file