Experiment: Move lint docs into markdown files

clippy_lints/docs/correctness/APPROX_CONSTANT.md

@@ -0,0 +1,24 @@
+**What it does:** Checks for floating point literals that approximate
+constants which are defined in
+[`std::f32::consts`](https://doc.rust-lang.org/stable/std/f32/consts/#constants)
+or
+[`std::f64::consts`](https://doc.rust-lang.org/stable/std/f64/consts/#constants),
+respectively, suggesting to use the predefined constant.
+
+**Why is this bad?** Usually, the definition in the standard library is more
+precise than what people come up with. If you find that your definition is
+actually more precise, please [file a Rust
+issue](https://github.com/rust-lang/rust/issues).
+
+**Known problems:** None.
+
+**Example:**
+```rust
+let x = 3.14;
+let y = 1_f64 / x;
+```
+Use predefined constants instead:
+```rust
+let x = std::f32::consts::PI;
+let y = std::f64::consts::FRAC_1_PI;
+```

clippy_lints/docs/restriction/INTEGER_ARITHMETIC.md

@@ -0,0 +1,19 @@
+**What it does:** Checks for integer arithmetic operations which could overflow or panic.
+
+Specifically, checks for any operators (`+`, `-`, `*`, `<<`, etc) which are capable
+of overflowing according to the [Rust
+Reference](https://doc.rust-lang.org/reference/expressions/operator-expr.html#overflow),
+or which can panic (`/`, `%`). No bounds analysis or sophisticated reasoning is
+attempted.
+
+**Why is this bad?** Integer overflow will trigger a panic in debug builds or will wrap in
+release mode. Division by zero will cause a panic in either mode. In some applications one
+wants explicitly checked, wrapping or saturating arithmetic.
+
+**Known problems:** None.
+
+**Example:**
+```rust
+# let a = 0;
+a + 1;
+```

clippy_lints/src/approx_const.rs

@@ -6,31 +6,7 @@ use rustc_session::{declare_lint_pass, declare_tool_lint};
 use rustc_span::symbol;
 use std::f64::consts as f64;
 
-declare_clippy_lint! {
-    /// **What it does:** Checks for floating point literals that approximate
-    /// constants which are defined in
-    /// [`std::f32::consts`](https://doc.rust-lang.org/stable/std/f32/consts/#constants)
-    /// or
-    /// [`std::f64::consts`](https://doc.rust-lang.org/stable/std/f64/consts/#constants),
-    /// respectively, suggesting to use the predefined constant.
-    ///
-    /// **Why is this bad?** Usually, the definition in the standard library is more
-    /// precise than what people come up with. If you find that your definition is
-    /// actually more precise, please [file a Rust
-    /// issue](https://github.com/rust-lang/rust/issues).
-    ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
-    /// ```rust
-    /// let x = 3.14;
-    /// let y = 1_f64 / x;
-    /// ```
-    /// Use predefined constants instead:
-    /// ```rust
-    /// let x = std::f32::consts::PI;
-    /// let y = std::f64::consts::FRAC_1_PI;
-    /// ```
+declare_clippy_lint_new! {
     pub APPROX_CONSTANT,
     correctness,
     "the approximate of a known float constant (in `std::fXX::consts`)"

clippy_lints/src/arithmetic.rs

@@ -5,26 +5,7 @@ use rustc_lint::{LateContext, LateLintPass};
 use rustc_session::{declare_tool_lint, impl_lint_pass};
 use rustc_span::source_map::Span;
 
-declare_clippy_lint! {
-    /// **What it does:** Checks for integer arithmetic operations which could overflow or panic.
-    ///
-    /// Specifically, checks for any operators (`+`, `-`, `*`, `<<`, etc) which are capable
-    /// of overflowing according to the [Rust
-    /// Reference](https://doc.rust-lang.org/reference/expressions/operator-expr.html#overflow),
-    /// or which can panic (`/`, `%`). No bounds analysis or sophisticated reasoning is
-    /// attempted.
-    ///
-    /// **Why is this bad?** Integer overflow will trigger a panic in debug builds or will wrap in
-    /// release mode. Division by zero will cause a panic in either mode. In some applications one
-    /// wants explicitly checked, wrapping or saturating arithmetic.
-    ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
-    /// ```rust
-    /// # let a = 0;
-    /// a + 1;
-    /// ```
+declare_clippy_lint_new! {
     pub INTEGER_ARITHMETIC,
     restriction,
     "any integer arithmetic expression which could overflow or panic"

clippy_lints/src/lib.rs

@@ -3,6 +3,7 @@
 #![feature(box_patterns)]
 #![feature(box_syntax)]
 #![feature(drain_filter)]
+#![feature(extended_key_value_attributes)]
 #![feature(in_band_lifetimes)]
 #![feature(once_cell)]
 #![feature(rustc_private)]
@@ -145,6 +146,16 @@ macro_rules! declare_clippy_lint {
     };
 }
 
+macro_rules! declare_clippy_lint_new {
+    { $(#[$attr:meta])* pub $name:tt, $category:tt $($tail:tt)* } => {
+        declare_clippy_lint! {
+            #[doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/docs/",
+                stringify!($category), "/", stringify!($name), ".md"))]
+            $(#[$attr])* pub $name, $category $($tail)*
+        }
+    };
+}
+
 #[macro_export]
 macro_rules! sym {
     ( $($x:tt)* ) => { clippy_utils::sym!($($x)*) }

util/lintlib.py

@@ -33,6 +33,7 @@ def parse_lints(lints, filepath):
     comment = []
     clippy = False
     deprecated = False
+    externaldoc = False
     name = ""
 
     with open(filepath) as fp:
@@ -60,11 +61,14 @@ def parse_lints(lints, filepath):
 
                     log.info("found %s with level %s in %s",
                              name, level, filepath)
+                    if externaldoc:
+                        comment = open(f"clippy_lints/docs/{group}/{name}.md").read().splitlines()
                     lints.append(Lint(name, level, comment, filepath, group))
                     comment = []
 
                     clippy = False
                     deprecated = False
+                    externaldoc = False
                     name = ""
                 else:
                     m = comment_re.search(line)
@@ -73,9 +77,15 @@ def parse_lints(lints, filepath):
             elif line.startswith("declare_clippy_lint!"):
                 clippy = True
                 deprecated = False
+                externaldoc = False
+            elif line.startswith("declare_clippy_lint_new!"):
+                clippy = True
+                deprecated = False
+                externaldoc = True
             elif line.startswith("declare_deprecated_lint!"):
                 clippy = False
                 deprecated = True
+                externaldoc = False
             elif line.startswith("declare_lint!"):
                 import sys
                 print(