Auto merge of #3845 - euclio:unused-comments, r=phansch

move lint documentation into macro invocations

This PR moves lint documentation inside `declare_clippy_lint!` macro invocations, to avoid triggering the `unused_doc_comments` lint once it's modified in rust-lang/rust#57882. This PR is necessary to unblock that work, since the large number of warnings generated in `clippy_lints` causes Travis to hit the log length limit.

This PR also updates the documentation and website generation script.

It would be nice to get a clippy update in the Rust repo once this is merged.

cc @phansch

clippy_dev/src/lib.rs

@@ -12,8 +12,9 @@ use walkdir::WalkDir;
 lazy_static! {
     static ref DEC_CLIPPY_LINT_RE: Regex = Regex::new(
         r#"(?x)
-        declare_clippy_lint!\s*[\{(]\s*
-        pub\s+(?P<name>[A-Z_][A-Z_0-9]*)\s*,\s*
+        declare_clippy_lint!\s*[\{(]
+        (?:\s+///.*)*
+        \s+pub\s+(?P<name>[A-Z_][A-Z_0-9]*)\s*,\s*
         (?P<cat>[a-z_]+)\s*,\s*
         "(?P<desc>(?:[^"\\]+|\\(?s).(?-s))*)"\s*[})]
     "#
@@ -22,7 +23,8 @@ lazy_static! {
     static ref DEC_DEPRECATED_LINT_RE: Regex = Regex::new(
         r#"(?x)
         declare_deprecated_lint!\s*[{(]\s*
-        pub\s+(?P<name>[A-Z_][A-Z_0-9]*)\s*,\s*
+        (?:\s+///.*)*
+        \s+pub\s+(?P<name>[A-Z_][A-Z_0-9]*)\s*,\s*
         "(?P<desc>(?:[^"\\]+|\\(?s).(?-s))*)"\s*[})]
     "#
     )

clippy_lints/src/approx_const.rs

@@ -6,28 +6,28 @@ use std::f64::consts as f64;
 use syntax::ast::{FloatTy, Lit, LitKind};
 use syntax::symbol;
 
-/// **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:** If you happen to have a value that is within 1/8192 of a
-/// known constant, but is not *and should not* be the same, this lint will
-/// report your value anyway. We have not yet noticed any false positives in
-/// code we tested clippy with (this includes servo), but YMMV.
-///
-/// **Example:**
-/// ```rust
-/// let x = 3.14;
-/// ```
 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:** If you happen to have a value that is within 1/8192 of a
+    /// known constant, but is not *and should not* be the same, this lint will
+    /// report your value anyway. We have not yet noticed any false positives in
+    /// code we tested clippy with (this includes servo), but YMMV.
+    ///
+    /// **Example:**
+    /// ```rust
+    /// let x = 3.14;
+    /// ```
     pub APPROX_CONSTANT,
     correctness,
     "the approximate of a known float constant (in `std::fXX::consts`)"

clippy_lints/src/arithmetic.rs

@@ -5,36 +5,36 @@ use rustc::lint::{LateContext, LateLintPass, LintArray, LintPass};
 use rustc::{declare_tool_lint, lint_array};
 use syntax::source_map::Span;
 
-/// **What it does:** Checks for plain integer arithmetic.
-///
-/// **Why is this bad?** This is only checked against overflow in debug builds.
-/// In some applications one wants explicitly checked, wrapping or saturating
-/// arithmetic.
-///
-/// **Known problems:** None.
-///
-/// **Example:**
-/// ```rust
-/// a + 1
-/// ```
 declare_clippy_lint! {
+    /// **What it does:** Checks for plain integer arithmetic.
+    ///
+    /// **Why is this bad?** This is only checked against overflow in debug builds.
+    /// In some applications one wants explicitly checked, wrapping or saturating
+    /// arithmetic.
+    ///
+    /// **Known problems:** None.
+    ///
+    /// **Example:**
+    /// ```rust
+    /// a + 1
+    /// ```
     pub INTEGER_ARITHMETIC,
     restriction,
     "any integer arithmetic statement"
 }
 
-/// **What it does:** Checks for float arithmetic.
-///
-/// **Why is this bad?** For some embedded systems or kernel development, it
-/// can be useful to rule out floating-point numbers.
-///
-/// **Known problems:** None.
-///
-/// **Example:**
-/// ```rust
-/// a + 1.0
-/// ```
 declare_clippy_lint! {
+    /// **What it does:** Checks for float arithmetic.
+    ///
+    /// **Why is this bad?** For some embedded systems or kernel development, it
+    /// can be useful to rule out floating-point numbers.
+    ///
+    /// **Known problems:** None.
+    ///
+    /// **Example:**
+    /// ```rust
+    /// a + 1.0
+    /// ```
     pub FLOAT_ARITHMETIC,
     restriction,
     "any floating-point arithmetic statement"

clippy_lints/src/assertions_on_constants.rs

@@ -6,23 +6,23 @@ use crate::syntax::ast::LitKind;
 use crate::utils::{in_macro, is_direct_expn_of, span_help_and_lint};
 use if_chain::if_chain;
 
-/// **What it does:** Check to call assert!(true/false)
-///
-/// **Why is this bad?** Will be optimized out by the compiler or should probably be replaced by a
-/// panic!() or unreachable!()
-///
-/// **Known problems:** None
-///
-/// **Example:**
-/// ```rust
-/// assert!(false)
-/// // or
-/// assert!(true)
-/// // or
-/// const B: bool = false;
-/// assert!(B)
-/// ```
 declare_clippy_lint! {
+    /// **What it does:** Check to call assert!(true/false)
+    ///
+    /// **Why is this bad?** Will be optimized out by the compiler or should probably be replaced by a
+    /// panic!() or unreachable!()
+    ///
+    /// **Known problems:** None
+    ///
+    /// **Example:**
+    /// ```no_run
+    /// assert!(false);
+    /// // or
+    /// assert!(true);
+    /// // or
+    /// const B: bool = false;
+    /// assert!(B);
+    /// ```
     pub ASSERTIONS_ON_CONSTANTS,
     style,
     "assert!(true/false) will be optimized out by the compiler/should probably be replaced by a panic!() or unreachable!()"

clippy_lints/src/assign_ops.rs

@@ -7,43 +7,43 @@ use rustc::lint::{LateContext, LateLintPass, LintArray, LintPass};
 use rustc::{declare_tool_lint, lint_array};
 use rustc_errors::Applicability;
 
-/// **What it does:** Checks for `a = a op b` or `a = b commutative_op a`
-/// patterns.
-///
-/// **Why is this bad?** These can be written as the shorter `a op= b`.
-///
-/// **Known problems:** While forbidden by the spec, `OpAssign` traits may have
-/// implementations that differ from the regular `Op` impl.
-///
-/// **Example:**
-/// ```rust
-/// let mut a = 5;
-/// ...
-/// a = a + b;
-/// ```
 declare_clippy_lint! {
+    /// **What it does:** Checks for `a = a op b` or `a = b commutative_op a`
+    /// patterns.
+    ///
+    /// **Why is this bad?** These can be written as the shorter `a op= b`.
+    ///
+    /// **Known problems:** While forbidden by the spec, `OpAssign` traits may have
+    /// implementations that differ from the regular `Op` impl.
+    ///
+    /// **Example:**
+    /// ```ignore
+    /// let mut a = 5;
+    /// ...
+    /// a = a + b;
+    /// ```
     pub ASSIGN_OP_PATTERN,
     style,
     "assigning the result of an operation on a variable to that same variable"
 }
 
-/// **What it does:** Checks for `a op= a op b` or `a op= b op a` patterns.
-///
-/// **Why is this bad?** Most likely these are bugs where one meant to write `a
-/// op= b`.
-///
-/// **Known problems:** Clippy cannot know for sure if `a op= a op b` should have
-/// been `a = a op a op b` or `a = a op b`/`a op= b`. Therefore it suggests both.
-/// If `a op= a op b` is really the correct behaviour it should be
-/// written as `a = a op a op b` as it's less confusing.
-///
-/// **Example:**
-/// ```rust
-/// let mut a = 5;
-/// ...
-/// a += a + b;
-/// ```
 declare_clippy_lint! {
+    /// **What it does:** Checks for `a op= a op b` or `a op= b op a` patterns.
+    ///
+    /// **Why is this bad?** Most likely these are bugs where one meant to write `a
+    /// op= b`.
+    ///
+    /// **Known problems:** Clippy cannot know for sure if `a op= a op b` should have
+    /// been `a = a op a op b` or `a = a op b`/`a op= b`. Therefore it suggests both.
+    /// If `a op= a op b` is really the correct behaviour it should be
+    /// written as `a = a op a op b` as it's less confusing.
+    ///
+    /// **Example:**
+    /// ```ignore
+    /// let mut a = 5;
+    /// ...
+    /// a += a + b;
+    /// ```
     pub MISREFACTORED_ASSIGN_OP,
     complexity,
     "having a variable on both sides of an assign op"