Add rustdoc doc page for lints

3 files changed, 126 insertions, 0 deletions

diff --git a/src/doc/rustdoc/src/SUMMARY.md b/src/doc/rustdoc/src/SUMMARY.md
index 63952f575fc..d4202f5b367 100644
--- a/src/doc/rustdoc/src/SUMMARY.md
+++ b/src/doc/rustdoc/src/SUMMARY.md
@@ -5,5 +5,6 @@
 - [Command-line arguments](command-line-arguments.md)
 - [The `#[doc]` attribute](the-doc-attribute.md)
 - [Documentation tests](documentation-tests.md)
+- [Lints](lints.md)
 - [Passes](passes.md)
 - [Unstable features](unstable-features.md)
diff --git a/src/doc/rustdoc/src/how-to-write-documentation.md b/src/doc/rustdoc/src/how-to-write-documentation.md
index b54233b00dc..dd3aa5d4b69 100644
--- a/src/doc/rustdoc/src/how-to-write-documentation.md
+++ b/src/doc/rustdoc/src/how-to-write-documentation.md
@@ -71,6 +71,12 @@ and finally provides a code example.
 `rustdoc` is using the [commonmark markdown specification]. You might be
 interested into taking a look at their website to see what's possible to do.
 
+## Lints
+
+To be sure that you didn't miss any item without documentation or code examples,
+you can take a look at the rustdoc lints [here][rustdoc-lints].
+
 [standard library]: https://doc.rust-lang.org/stable/std/index.html
 [env::args]: https://doc.rust-lang.org/stable/std/env/fn.args.html
 [commonmark markdown specification]: https://commonmark.org/
+[rustdoc-lints]: lints.md
diff --git a/src/doc/rustdoc/src/lints.md b/src/doc/rustdoc/src/lints.md
new file mode 100644
index 00000000000..beb2556872d
--- /dev/null
+++ b/src/doc/rustdoc/src/lints.md
@@ -0,0 +1,119 @@
+# Lints
+
+`rustdoc` provides lints to help you writing and testing your documentation. You
+can use them like any other lints by doing this:
+
+```rust,ignore
+#![allow(missing_docs)] // allowing the lint, no message
+#![warn(missing_docs)] // warn if there is missing docs
+#![deny(missing_docs)] // rustdoc will fail if there is missing docs
+```
+
+Here is the list of the lints provided by `rustdoc`:
+
+## intra_doc_link_resolution_failure
+
+This lint **warns by default** and is **nightly-only**. This lint detects when
+an intra-doc link fails to get resolved. For example:
+
+```rust
+/// I want to link to [`Inexistent`] but it doesn't exist!
+pub fn foo() {}
+```
+
+You'll get a warning saying:
+
+```text
+error: `[`Inexistent`]` cannot be resolved, ignoring it...
+```
+
+## missing_docs
+
+This lint is **allowed by default**. It detects items missing documentation.
+For example:
+
+```rust
+#![warn(missing_docs)]
+
+pub fn undocumented() {}
+# fn main() {}
+```
+
+The `undocumented` function will then have the following warning:
+
+```text
+warning: missing documentation for a function
+  --> your-crate/lib.rs:3:1
+   |
+ 3 | pub fn undocumented() {}
+   | ^^^^^^^^^^^^^^^^^^^^^
+```
+
+## missing_doc_code_examples
+
+This lint is **allowed by default**. It detects when a documentation block
+is missing a code example. For example:
+
+```rust
+#![warn(missing_doc_code_examples)]
+
+/// There is no code example!
+pub fn no_code_example() {}
+# fn main() {}
+```
+
+The `no_code_example` function will then have the following warning:
+
+```text
+warning: Missing code example in this documentation
+  --> your-crate/lib.rs:3:1
+   |
+LL | /// There is no code example!
+   | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+```
+
+To fix the lint, you need to add a code example into the documentation block:
+
+```rust
+/// There is no code example!
+///
+/// ```
+/// println!("calling no_code_example...");
+/// no_code_example();
+/// println!("we called no_code_example!");
+/// ```
+pub fn no_code_example() {}
+```
+
+## private_doc_tests
+
+This lint is **allowed by default**. It detects documentation tests when they
+are on a private item. For example:
+
+```rust
+#![warn(private_doc_tests)]
+
+mod foo {
+    /// private doc test
+    ///
+    /// ```
+    /// assert!(false);
+    /// ```
+    fn bar() {}
+}
+# fn main() {}
+```
+
+Which will give:
+
+```text
+warning: Documentation test in private item
+  --> your-crate/lib.rs:4:1
+   |
+ 4 | /     /// private doc test
+ 5 | |     ///
+ 6 | |     /// ```
+ 7 | |     /// assert!(false);
+ 8 | |     /// ```
+   | |___________^
+```