New rustdoc lint to respect -Dwarnings correctly

This adds a new lint to `rustc` that is used in rustdoc when a code
block is empty or cannot be parsed as valid Rust code.

Previously this was unconditionally a warning. As such some
documentation comments were (unknowingly) abusing this to pass despite
the `-Dwarnings` used when compiling `rustc`, this should not be the
case anymore.

1 files changed, 37 insertions, 0 deletions

diff --git a/src/doc/rustdoc/src/lints.md b/src/doc/rustdoc/src/lints.md
index a6626679a7d..7088e60aa07 100644
--- a/src/doc/rustdoc/src/lints.md
+++ b/src/doc/rustdoc/src/lints.md
@@ -294,6 +294,43 @@ warning: unclosed HTML tag `h1`
 warning: 2 warnings emitted
 ```
 
+## invalid_rust_codeblock
+
+This lint **warns by default**. It detects Rust code blocks in documentation
+examples that are invalid (e.g. empty, not parsable as Rust). For example:
+
+```rust
+/// Empty code blocks (with and without the `rust` marker):
+///
+/// ```rust
+/// ```
+///
+/// Unclosed code blocks (with and without the `rust` marker):
+///
+/// ```rust
+fn main() {}
+```
+
+Which will give:
+
+```text
+warning: Rust code block is empty
+--> src/lib.rs:3:5
+|
+3 |   /// ```rust
+|  _____^
+4 | | /// ```
+| |_______^
+|
+= note: `#[warn(rustdoc::invalid_rust_codeblock)]` on by default
+
+warning: Rust code block is empty
+--> src/lib.rs:8:5
+|
+8 | /// ```rust
+|     ^^^^^^^
+```
+
 ## bare_urls
 
 This lint is **warn-by-default**. It detects URLs which are not links.