Update lint documentation to use markdown headlines

clippy_dev/src/new_lint.rs

@@ -169,14 +169,11 @@ use rustc_session::{{declare_lint_pass, declare_tool_lint}};
 {pass_import}
 
 declare_clippy_lint! {{
-    /// **What it does:**
+    /// ### What it does
     ///
-    /// **Why is this bad?**
-    ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Why is this bad?
     ///
+    /// ### Example
     /// ```rust
     /// // example code where clippy issues a warning
     /// ```

clippy_lints/src/absurd_extreme_comparisons.rs

@@ -11,24 +11,26 @@ use clippy_utils::ty::is_isize_or_usize;
 use clippy_utils::{clip, int_bits, unsext};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for comparisons where one side of the relation is
+    /// ### What it does
+    /// Checks for comparisons where one side of the relation is
     /// either the minimum or maximum value for its type and warns if it involves a
     /// case that is always true or always false. Only integer and boolean types are
     /// checked.
     ///
-    /// **Why is this bad?** An expression like `min <= x` may misleadingly imply
+    /// ### Why is this bad?
+    /// An expression like `min <= x` may misleadingly imply
     /// that it is possible for `x` to be less than the minimum. Expressions like
     /// `max < x` are probably mistakes.
     ///
-    /// **Known problems:** For `usize` the size of the current compile target will
+    /// ### Known problems
+    /// For `usize` the size of the current compile target will
     /// be assumed (e.g., 64 bits on 64 bit systems). This means code that uses such
     /// a comparison to detect target pointer width will trigger this lint. One can
     /// use `mem::sizeof` and compare its value or conditional compilation
     /// attributes
     /// like `#[cfg(target_pointer_width = "64")] ..` instead.
     ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust
     /// let vec: Vec<isize> = Vec::new();
     /// if vec.len() <= 0 {}

clippy_lints/src/approx_const.rs

@@ -7,21 +7,21 @@ use rustc_span::symbol;
 use std::f64::consts as f64;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for floating point literals that approximate
+    /// ### 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
+    /// ### 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:**
+    /// ### Example
     /// ```rust
     /// let x = 3.14;
     /// let y = 1_f64 / x;

clippy_lints/src/arithmetic.rs

@@ -6,21 +6,21 @@ 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.
+    /// ### 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
+    /// ### 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:**
+    /// ### Example
     /// ```rust
     /// # let a = 0;
     /// a + 1;
@@ -31,14 +31,14 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for float arithmetic.
+    /// ### What it does
+    /// Checks for float arithmetic.
     ///
-    /// **Why is this bad?** For some embedded systems or kernel development, it
+    /// ### 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:**
+    /// ### Example
     /// ```rust
     /// # let a = 0.0;
     /// a + 1.0;

clippy_lints/src/as_conversions.rs

@@ -5,7 +5,8 @@ use rustc_middle::lint::in_external_macro;
 use rustc_session::{declare_lint_pass, declare_tool_lint};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for usage of `as` conversions.
+    /// ### What it does
+    /// Checks for usage of `as` conversions.
     ///
     /// Note that this lint is specialized in linting *every single* use of `as`
     /// regardless of whether good alternatives exist or not.
@@ -15,14 +16,13 @@ declare_clippy_lint! {
     /// There is a good explanation the reason why this lint should work in this way and how it is useful
     /// [in this issue](https://github.com/rust-lang/rust-clippy/issues/5122).
     ///
-    /// **Why is this bad?** `as` conversions will perform many kinds of
+    /// ### Why is this bad?
+    /// `as` conversions will perform many kinds of
     /// conversions, including silently lossy conversions and dangerous coercions.
     /// There are cases when it makes sense to use `as`, so the lint is
     /// Allow by default.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust,ignore
     /// let a: u32;
     /// ...

clippy_lints/src/asm_syntax.rs

@@ -53,14 +53,14 @@ fn check_expr_asm_syntax(lint: &'static Lint, cx: &EarlyContext<'_>, expr: &Expr
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for usage of Intel x86 assembly syntax.
+    /// ### What it does
+    /// Checks for usage of Intel x86 assembly syntax.
     ///
-    /// **Why is this bad?** The lint has been enabled to indicate a preference
+    /// ### Why is this bad?
+    /// The lint has been enabled to indicate a preference
     /// for AT&T x86 assembly syntax.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     ///
     /// ```rust,no_run
     /// # #![feature(asm)]
@@ -89,14 +89,14 @@ impl EarlyLintPass for InlineAsmX86IntelSyntax {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for usage of AT&T x86 assembly syntax.
+    /// ### What it does
+    /// Checks for usage of AT&T x86 assembly syntax.
     ///
-    /// **Why is this bad?** The lint has been enabled to indicate a preference
+    /// ### Why is this bad?
+    /// The lint has been enabled to indicate a preference
     /// for Intel x86 assembly syntax.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     ///
     /// ```rust,no_run
     /// # #![feature(asm)]

clippy_lints/src/assertions_on_constants.rs

@@ -8,14 +8,17 @@ use rustc_lint::{LateContext, LateLintPass};
 use rustc_session::{declare_lint_pass, declare_tool_lint};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for `assert!(true)` and `assert!(false)` calls.
+    /// ### What it does
+    /// Checks for `assert!(true)` and `assert!(false)` calls.
     ///
-    /// **Why is this bad?** Will be optimized out by the compiler or should probably be replaced by a
+    /// ### Why is this bad?
+    /// Will be optimized out by the compiler or should probably be replaced by a
     /// `panic!()` or `unreachable!()`
     ///
-    /// **Known problems:** None
+    /// ### Known problems
+    /// None
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust,ignore
     /// assert!(false)
     /// assert!(true)

clippy_lints/src/assign_ops.rs

@@ -12,15 +12,18 @@ use rustc_middle::hir::map::Map;
 use rustc_session::{declare_lint_pass, declare_tool_lint};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for `a = a op b` or `a = b commutative_op a`
+    /// ### 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`.
+    /// ### 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
+    /// ### Known problems
+    /// While forbidden by the spec, `OpAssign` traits may have
     /// implementations that differ from the regular `Op` impl.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// let mut a = 5;
     /// let b = 0;
@@ -37,17 +40,20 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for `a op= a op b` or `a op= b op a` patterns.
+    /// ### 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
+    /// ### 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
+    /// ### 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:**
+    /// ### Example
     /// ```rust
     /// let mut a = 5;
     /// let b = 2;

clippy_lints/src/async_yields_async.rs

@@ -7,15 +7,14 @@ use rustc_lint::{LateContext, LateLintPass};
 use rustc_session::{declare_lint_pass, declare_tool_lint};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for async blocks that yield values of types
+    /// ### What it does
+    /// Checks for async blocks that yield values of types
     /// that can themselves be awaited.
     ///
-    /// **Why is this bad?** An await is likely missing.
-    ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Why is this bad?
+    /// An await is likely missing.
     ///
+    /// ### Example
     /// ```rust
     /// async fn foo() {}
     ///

clippy_lints/src/atomic_ordering.rs

@@ -8,16 +8,16 @@ use rustc_middle::ty;
 use rustc_session::{declare_lint_pass, declare_tool_lint};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for usage of invalid atomic
+    /// ### What it does
+    /// Checks for usage of invalid atomic
     /// ordering in atomic loads/stores/exchanges/updates and
     /// memory fences.
     ///
-    /// **Why is this bad?** Using an invalid atomic ordering
+    /// ### Why is this bad?
+    /// Using an invalid atomic ordering
     /// will cause a panic at run-time.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust,no_run
     /// # use std::sync::atomic::{self, AtomicU8, Ordering};
     ///