diff --git a/clippy_dev/src/new_lint.rs b/clippy_dev/src/new_lint.rs
index 4676c2affad79..3a81aaba6de04 100644
--- a/clippy_dev/src/new_lint.rs
+++ b/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
     /// ```
diff --git a/clippy_lints/src/absurd_extreme_comparisons.rs b/clippy_lints/src/absurd_extreme_comparisons.rs
index 49d4350123f4b..1483f3f9185ae 100644
--- a/clippy_lints/src/absurd_extreme_comparisons.rs
+++ b/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 {}
diff --git a/clippy_lints/src/approx_const.rs b/clippy_lints/src/approx_const.rs
index 3d04abe094d78..6100f4e435a8a 100644
--- a/clippy_lints/src/approx_const.rs
+++ b/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;
diff --git a/clippy_lints/src/arithmetic.rs b/clippy_lints/src/arithmetic.rs
index 24c2a9728111f..36fe7b7a86754 100644
--- a/clippy_lints/src/arithmetic.rs
+++ b/clippy_lints/src/arithmetic.rs
@@ -6,7 +6,8 @@ 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
@@ -14,13 +15,12 @@ declare_clippy_lint! {
     /// 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;
diff --git a/clippy_lints/src/as_conversions.rs b/clippy_lints/src/as_conversions.rs
index 4b31e16094e9f..7c39a3e2ce3de 100644
--- a/clippy_lints/src/as_conversions.rs
+++ b/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;
     /// ...
diff --git a/clippy_lints/src/asm_syntax.rs b/clippy_lints/src/asm_syntax.rs
index b970c71b753ce..825832eb79dab 100644
--- a/clippy_lints/src/asm_syntax.rs
+++ b/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)]
diff --git a/clippy_lints/src/assertions_on_constants.rs b/clippy_lints/src/assertions_on_constants.rs
index 5235b2642d18c..cb9347a923d87 100644
--- a/clippy_lints/src/assertions_on_constants.rs
+++ b/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)
diff --git a/clippy_lints/src/assign_ops.rs b/clippy_lints/src/assign_ops.rs
index 17ce3cd809f6f..2097a1feff9f3 100644
--- a/clippy_lints/src/assign_ops.rs
+++ b/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;
diff --git a/clippy_lints/src/async_yields_async.rs b/clippy_lints/src/async_yields_async.rs
index e6c7c68f91a07..182736a5a205a 100644
--- a/clippy_lints/src/async_yields_async.rs
+++ b/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() {}
     ///
diff --git a/clippy_lints/src/atomic_ordering.rs b/clippy_lints/src/atomic_ordering.rs
index 7ceb01f5590fc..cece28e8b3c3f 100644
--- a/clippy_lints/src/atomic_ordering.rs
+++ b/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};
     ///
diff --git a/clippy_lints/src/attrs.rs b/clippy_lints/src/attrs.rs
index f272ed010a1b0..c9ff468874b58 100644
--- a/clippy_lints/src/attrs.rs
+++ b/clippy_lints/src/attrs.rs
@@ -41,10 +41,12 @@ static UNIX_SYSTEMS: &[&str] = &[
 static NON_UNIX_SYSTEMS: &[&str] = &["hermit", "none", "wasi"];
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for items annotated with `#[inline(always)]`,
+    /// ### What it does
+    /// Checks for items annotated with `#[inline(always)]`,
     /// unless the annotated function is empty or simply panics.
     ///
-    /// **Why is this bad?** While there are valid uses of this annotation (and once
+    /// ### Why is this bad?
+    /// While there are valid uses of this annotation (and once
     /// you know when to use it, by all means `allow` this lint), it's a common
     /// newbie-mistake to pepper one's code with it.
     ///
@@ -52,11 +54,12 @@ declare_clippy_lint! {
     /// measure if that additional function call really affects your runtime profile
     /// sufficiently to make up for the increase in compile time.
     ///
-    /// **Known problems:** False positives, big time. This lint is meant to be
+    /// ### Known problems
+    /// False positives, big time. This lint is meant to be
     /// deactivated by everyone doing serious performance work. This means having
     /// done the measurement.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```ignore
     /// #[inline(always)]
     /// fn not_quite_hot_code(..) { ... }
@@ -67,7 +70,8 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for `extern crate` and `use` items annotated with
+    /// ### What it does
+    /// Checks for `extern crate` and `use` items annotated with
     /// lint attributes.
     ///
     /// This lint permits `#[allow(unused_imports)]`, `#[allow(deprecated)]`,
@@ -75,12 +79,11 @@ declare_clippy_lint! {
     /// `#[allow(clippy::enum_glob_use)]` on `use` items and `#[allow(unused_imports)]` on
     /// `extern crate` items with a `#[macro_use]` attribute.
     ///
-    /// **Why is this bad?** Lint attributes have no effect on crate imports. Most
+    /// ### Why is this bad?
+    /// Lint attributes have no effect on crate imports. Most
     /// likely a `!` was forgotten.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```ignore
     /// // Bad
     /// #[deny(dead_code)]
@@ -101,15 +104,15 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for `#[deprecated]` annotations with a `since`
+    /// ### What it does
+    /// Checks for `#[deprecated]` annotations with a `since`
     /// field that is not a valid semantic version.
     ///
-    /// **Why is this bad?** For checking the version of the deprecation, it must be
+    /// ### Why is this bad?
+    /// For checking the version of the deprecation, it must be
     /// a valid semver. Failing that, the contained information is useless.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// #[deprecated(since = "forever")]
     /// fn something_else() { /* ... */ }
@@ -120,20 +123,22 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for empty lines after outer attributes
+    /// ### What it does
+    /// Checks for empty lines after outer attributes
     ///
-    /// **Why is this bad?**
+    /// ### Why is this bad?
     /// Most likely the attribute was meant to be an inner attribute using a '!'.
     /// If it was meant to be an outer attribute, then the following item
     /// should not be separated by empty lines.
     ///
-    /// **Known problems:** Can cause false positives.
+    /// ### Known problems
+    /// Can cause false positives.
     ///
     /// From the clippy side it's difficult to detect empty lines between an attributes and the
     /// following item because empty lines and comments are not part of the AST. The parsing
     /// currently works for basic cases but is not perfect.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// // Good (as inner attribute)
     /// #![allow(dead_code)]
@@ -155,14 +160,14 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for `warn`/`deny`/`forbid` attributes targeting the whole clippy::restriction category.
+    /// ### What it does
+    /// Checks for `warn`/`deny`/`forbid` attributes targeting the whole clippy::restriction category.
     ///
-    /// **Why is this bad?** Restriction lints sometimes are in contrast with other lints or even go against idiomatic rust.
+    /// ### Why is this bad?
+    /// Restriction lints sometimes are in contrast with other lints or even go against idiomatic rust.
     /// These lints should only be enabled on a lint-by-lint basis and with careful consideration.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// Bad:
     /// ```rust
     /// #![deny(clippy::restriction)]
@@ -178,18 +183,20 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for `#[cfg_attr(rustfmt, rustfmt_skip)]` and suggests to replace it
+    /// ### What it does
+    /// Checks for `#[cfg_attr(rustfmt, rustfmt_skip)]` and suggests to replace it
     /// with `#[rustfmt::skip]`.
     ///
-    /// **Why is this bad?** Since tool_attributes ([rust-lang/rust#44690](https://github.com/rust-lang/rust/issues/44690))
+    /// ### Why is this bad?
+    /// Since tool_attributes ([rust-lang/rust#44690](https://github.com/rust-lang/rust/issues/44690))
     /// are stable now, they should be used instead of the old `cfg_attr(rustfmt)` attributes.
     ///
-    /// **Known problems:** This lint doesn't detect crate level inner attributes, because they get
+    /// ### Known problems
+    /// This lint doesn't detect crate level inner attributes, because they get
     /// processed before the PreExpansionPass lints get executed. See
     /// [#3123](https://github.com/rust-lang/rust-clippy/pull/3123#issuecomment-422321765)
     ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// Bad:
     /// ```rust
     /// #[cfg_attr(rustfmt, rustfmt_skip)]
@@ -207,15 +214,14 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for cfg attributes having operating systems used in target family position.
+    /// ### What it does
+    /// Checks for cfg attributes having operating systems used in target family position.
     ///
-    /// **Why is this bad?** The configuration option will not be recognised and the related item will not be included
+    /// ### Why is this bad?
+    /// The configuration option will not be recognised and the related item will not be included
     /// by the conditional compilation engine.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// Bad:
     /// ```rust
     /// #[cfg(linux)]
diff --git a/clippy_lints/src/await_holding_invalid.rs b/clippy_lints/src/await_holding_invalid.rs
index 1739a57a240b2..0cc79c8b6e8cb 100644
--- a/clippy_lints/src/await_holding_invalid.rs
+++ b/clippy_lints/src/await_holding_invalid.rs
@@ -8,10 +8,12 @@ use rustc_session::{declare_lint_pass, declare_tool_lint};
 use rustc_span::Span;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for calls to await while holding a
+    /// ### What it does
+    /// Checks for calls to await while holding a
     /// non-async-aware MutexGuard.
     ///
-    /// **Why is this bad?** The Mutex types found in std::sync and parking_lot
+    /// ### Why is this bad?
+    /// The Mutex types found in std::sync and parking_lot
     /// are not designed to operate in an async context across await points.
     ///
     /// There are two potential solutions. One is to use an asynx-aware Mutex
@@ -19,10 +21,10 @@ declare_clippy_lint! {
     /// other solution is to ensure the mutex is unlocked before calling await,
     /// either by introducing a scope or an explicit call to Drop::drop.
     ///
-    /// **Known problems:** Will report false positive for explicitly dropped guards ([#6446](https://github.com/rust-lang/rust-clippy/issues/6446)).
-    ///
-    /// **Example:**
+    /// ### Known problems
+    /// Will report false positive for explicitly dropped guards ([#6446](https://github.com/rust-lang/rust-clippy/issues/6446)).
     ///
+    /// ### Example
     /// ```rust,ignore
     /// use std::sync::Mutex;
     ///
@@ -51,17 +53,19 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for calls to await while holding a
+    /// ### What it does
+    /// Checks for calls to await while holding a
     /// `RefCell` `Ref` or `RefMut`.
     ///
-    /// **Why is this bad?** `RefCell` refs only check for exclusive mutable access
+    /// ### Why is this bad?
+    /// `RefCell` refs only check for exclusive mutable access
     /// at runtime. Holding onto a `RefCell` ref across an `await` suspension point
     /// risks panics from a mutable ref shared while other refs are outstanding.
     ///
-    /// **Known problems:** Will report false positive for explicitly dropped refs ([#6353](https://github.com/rust-lang/rust-clippy/issues/6353)).
-    ///
-    /// **Example:**
+    /// ### Known problems
+    /// Will report false positive for explicitly dropped refs ([#6353](https://github.com/rust-lang/rust-clippy/issues/6353)).
     ///
+    /// ### Example
     /// ```rust,ignore
     /// use std::cell::RefCell;
     ///
diff --git a/clippy_lints/src/bit_mask.rs b/clippy_lints/src/bit_mask.rs
index 991ed94572c7e..11346e7c96af9 100644
--- a/clippy_lints/src/bit_mask.rs
+++ b/clippy_lints/src/bit_mask.rs
@@ -10,7 +10,8 @@ use rustc_session::{declare_tool_lint, impl_lint_pass};
 use rustc_span::source_map::Span;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for incompatible bit masks in comparisons.
+    /// ### What it does
+    /// Checks for incompatible bit masks in comparisons.
     ///
     /// The formula for detecting if an expression of the type `_ <bit_op> m
     /// <cmp_op> c` (where `<bit_op>` is one of {`&`, `|`} and `<cmp_op>` is one of
@@ -26,7 +27,8 @@ declare_clippy_lint! {
     /// |`<`  or `>=`| `|`  |`x | 1 < 1` |`false`  |`m >= c`              |
     /// |`<=` or `>` | `|`  |`x | 1 > 0` |`true`   |`m > c`               |
     ///
-    /// **Why is this bad?** If the bits that the comparison cares about are always
+    /// ### Why is this bad?
+    /// If the bits that the comparison cares about are always
     /// set to zero or one by the bit mask, the comparison is constant `true` or
     /// `false` (depending on mask, compared value, and operators).
     ///
@@ -34,9 +36,7 @@ declare_clippy_lint! {
     /// this intentionally is to win an underhanded Rust contest or create a
     /// test-case for this lint.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # let x = 1;
     /// if (x & 1 == 2) { }
@@ -47,7 +47,8 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for bit masks in comparisons which can be removed
+    /// ### What it does
+    /// Checks for bit masks in comparisons which can be removed
     /// without changing the outcome. The basic structure can be seen in the
     /// following table:
     ///
@@ -56,16 +57,18 @@ declare_clippy_lint! {
     /// |`>` / `<=`|`|` / `^`|`x | 2 > 3`|`x > 3`|
     /// |`<` / `>=`|`|` / `^`|`x ^ 1 < 4`|`x < 4`|
     ///
-    /// **Why is this bad?** Not equally evil as [`bad_bit_mask`](#bad_bit_mask),
+    /// ### Why is this bad?
+    /// Not equally evil as [`bad_bit_mask`](#bad_bit_mask),
     /// but still a bit misleading, because the bit mask is ineffective.
     ///
-    /// **Known problems:** False negatives: This lint will only match instances
+    /// ### Known problems
+    /// False negatives: This lint will only match instances
     /// where we have figured out the math (which is for a power-of-two compared
     /// value). This means things like `x | 1 >= 7` (which would be better written
     /// as `x >= 6`) will not be reported (but bit masks like this are fairly
     /// uncommon).
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # let x = 1;
     /// if (x | 1 > 3) {  }
@@ -76,15 +79,18 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for bit masks that can be replaced by a call
+    /// ### What it does
+    /// Checks for bit masks that can be replaced by a call
     /// to `trailing_zeros`
     ///
-    /// **Why is this bad?** `x.trailing_zeros() > 4` is much clearer than `x & 15
+    /// ### Why is this bad?
+    /// `x.trailing_zeros() > 4` is much clearer than `x & 15
     /// == 0`
     ///
-    /// **Known problems:** llvm generates better code for `x & 15 == 0` on x86
+    /// ### Known problems
+    /// llvm generates better code for `x & 15 == 0` on x86
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # let x = 1;
     /// if x & 0b1111 == 0 { }
diff --git a/clippy_lints/src/blacklisted_name.rs b/clippy_lints/src/blacklisted_name.rs
index 8eb94f3c28e44..916c78c982ae4 100644
--- a/clippy_lints/src/blacklisted_name.rs
+++ b/clippy_lints/src/blacklisted_name.rs
@@ -5,15 +5,15 @@ use rustc_lint::{LateContext, LateLintPass};
 use rustc_session::{declare_tool_lint, impl_lint_pass};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for usage of blacklisted names for variables, such
+    /// ### What it does
+    /// Checks for usage of blacklisted names for variables, such
     /// as `foo`.
     ///
-    /// **Why is this bad?** These names are usually placeholder names and should be
+    /// ### Why is this bad?
+    /// These names are usually placeholder names and should be
     /// avoided.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// let foo = 3.14;
     /// ```
diff --git a/clippy_lints/src/blocks_in_if_conditions.rs b/clippy_lints/src/blocks_in_if_conditions.rs
index badcf8d2a43cd..9b2e4f8998e4e 100644
--- a/clippy_lints/src/blocks_in_if_conditions.rs
+++ b/clippy_lints/src/blocks_in_if_conditions.rs
@@ -13,14 +13,14 @@ use rustc_session::{declare_lint_pass, declare_tool_lint};
 use rustc_span::sym;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for `if` conditions that use blocks containing an
+    /// ### What it does
+    /// Checks for `if` conditions that use blocks containing an
     /// expression, statements or conditions that use closures with blocks.
     ///
-    /// **Why is this bad?** Style, using blocks in the condition makes it hard to read.
+    /// ### Why is this bad?
+    /// Style, using blocks in the condition makes it hard to read.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Examples:**
+    /// ### Examples
     /// ```rust
     /// // Bad
     /// if { true } { /* ... */ }
diff --git a/clippy_lints/src/bool_assert_comparison.rs b/clippy_lints/src/bool_assert_comparison.rs
index bee706ed40215..8d3f68565b223 100644
--- a/clippy_lints/src/bool_assert_comparison.rs
+++ b/clippy_lints/src/bool_assert_comparison.rs
@@ -6,14 +6,13 @@ use rustc_lint::{EarlyContext, EarlyLintPass};
 use rustc_session::{declare_lint_pass, declare_tool_lint};
 
 declare_clippy_lint! {
-    /// **What it does:** This lint warns about boolean comparisons in assert-like macros.
+    /// ### What it does
+    /// This lint warns about boolean comparisons in assert-like macros.
     ///
-    /// **Why is this bad?** It is shorter to use the equivalent.
-    ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Why is this bad?
+    /// It is shorter to use the equivalent.
     ///
+    /// ### Example
     /// ```rust
     /// // Bad
     /// assert_eq!("a".is_empty(), false);
diff --git a/clippy_lints/src/booleans.rs b/clippy_lints/src/booleans.rs
index e72399af232b5..4a83d35a568c5 100644
--- a/clippy_lints/src/booleans.rs
+++ b/clippy_lints/src/booleans.rs
@@ -14,16 +14,19 @@ use rustc_span::source_map::Span;
 use rustc_span::sym;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for boolean expressions that can be written more
+    /// ### What it does
+    /// Checks for boolean expressions that can be written more
     /// concisely.
     ///
-    /// **Why is this bad?** Readability of boolean expressions suffers from
+    /// ### Why is this bad?
+    /// Readability of boolean expressions suffers from
     /// unnecessary duplication.
     ///
-    /// **Known problems:** Ignores short circuiting behavior of `||` and
+    /// ### Known problems
+    /// Ignores short circuiting behavior of `||` and
     /// `&&`. Ignores `|`, `&` and `^`.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```ignore
     /// if a && true  // should be: if a
     /// if !(a == b)  // should be: if a != b
@@ -34,14 +37,17 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for boolean expressions that contain terminals that
+    /// ### What it does
+    /// Checks for boolean expressions that contain terminals that
     /// can be eliminated.
     ///
-    /// **Why is this bad?** This is most likely a logic bug.
+    /// ### Why is this bad?
+    /// This is most likely a logic bug.
     ///
-    /// **Known problems:** Ignores short circuiting behavior.
+    /// ### Known problems
+    /// Ignores short circuiting behavior.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```ignore
     /// if a && b || a { ... }
     /// ```
diff --git a/clippy_lints/src/bytecount.rs b/clippy_lints/src/bytecount.rs
index 4f7ffdcdfb499..c444984bc133a 100644
--- a/clippy_lints/src/bytecount.rs
+++ b/clippy_lints/src/bytecount.rs
@@ -12,18 +12,20 @@ use rustc_session::{declare_lint_pass, declare_tool_lint};
 use rustc_span::sym;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for naive byte counts
+    /// ### What it does
+    /// Checks for naive byte counts
     ///
-    /// **Why is this bad?** The [`bytecount`](https://crates.io/crates/bytecount)
+    /// ### Why is this bad?
+    /// The [`bytecount`](https://crates.io/crates/bytecount)
     /// crate has methods to count your bytes faster, especially for large slices.
     ///
-    /// **Known problems:** If you have predominantly small slices, the
+    /// ### Known problems
+    /// If you have predominantly small slices, the
     /// `bytecount::count(..)` method may actually be slower. However, if you can
     /// ensure that less than 2³²-1 matches arise, the `naive_count_32(..)` can be
     /// faster in those cases.
     ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust
     /// # let vec = vec![1_u8];
     /// &vec.iter().filter(|x| **x == 0u8).count(); // use bytecount::count instead
diff --git a/clippy_lints/src/cargo_common_metadata.rs b/clippy_lints/src/cargo_common_metadata.rs
index 21c7b2448cec8..bd5426ba707a8 100644
--- a/clippy_lints/src/cargo_common_metadata.rs
+++ b/clippy_lints/src/cargo_common_metadata.rs
@@ -9,15 +9,15 @@ use rustc_session::{declare_tool_lint, impl_lint_pass};
 use rustc_span::source_map::DUMMY_SP;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks to see if all common metadata is defined in
+    /// ### What it does
+    /// Checks to see if all common metadata is defined in
     /// `Cargo.toml`. See: https://rust-lang-nursery.github.io/api-guidelines/documentation.html#cargotoml-includes-all-common-metadata-c-metadata
     ///
-    /// **Why is this bad?** It will be more difficult for users to discover the
+    /// ### Why is this bad?
+    /// It will be more difficult for users to discover the
     /// purpose of the crate, and key information related to it.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```toml
     /// # This `Cargo.toml` is missing a description field:
     /// [package]
diff --git a/clippy_lints/src/case_sensitive_file_extension_comparisons.rs b/clippy_lints/src/case_sensitive_file_extension_comparisons.rs
index c9ef379be565d..86b32475cebdc 100644
--- a/clippy_lints/src/case_sensitive_file_extension_comparisons.rs
+++ b/clippy_lints/src/case_sensitive_file_extension_comparisons.rs
@@ -8,17 +8,14 @@ use rustc_session::{declare_lint_pass, declare_tool_lint};
 use rustc_span::{source_map::Spanned, symbol::sym, Span};
 
 declare_clippy_lint! {
-    /// **What it does:**
+    /// ### What it does
     /// Checks for calls to `ends_with` with possible file extensions
     /// and suggests to use a case-insensitive approach instead.
     ///
-    /// **Why is this bad?**
+    /// ### Why is this bad?
     /// `ends_with` is case-sensitive and may not detect files with a valid extension.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust
     /// fn is_rust_file(filename: &str) -> bool {
     ///     filename.ends_with(".rs")
diff --git a/clippy_lints/src/casts/mod.rs b/clippy_lints/src/casts/mod.rs
index ae4fdd12c41e8..27e1bea799353 100644
--- a/clippy_lints/src/casts/mod.rs
+++ b/clippy_lints/src/casts/mod.rs
@@ -20,7 +20,8 @@ use rustc_semver::RustcVersion;
 use rustc_session::{declare_tool_lint, impl_lint_pass};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for casts from any numerical to a float type where
+    /// ### What it does
+    /// Checks for casts from any numerical to a float type where
     /// the receiving type cannot store all values from the original type without
     /// rounding errors. This possible rounding is to be expected, so this lint is
     /// `Allow` by default.
@@ -28,13 +29,12 @@ declare_clippy_lint! {
     /// Basically, this warns on casting any integer with 32 or more bits to `f32`
     /// or any 64-bit integer to `f64`.
     ///
-    /// **Why is this bad?** It's not bad at all. But in some applications it can be
+    /// ### Why is this bad?
+    /// It's not bad at all. But in some applications it can be
     /// helpful to know where precision loss can take place. This lint can help find
     /// those places in the code.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// let x = u64::MAX;
     /// x as f64;
@@ -45,17 +45,17 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for casts from a signed to an unsigned numerical
+    /// ### What it does
+    /// Checks for casts from a signed to an unsigned numerical
     /// type. In this case, negative values wrap around to large positive values,
     /// which can be quite surprising in practice. However, as the cast works as
     /// defined, this lint is `Allow` by default.
     ///
-    /// **Why is this bad?** Possibly surprising results. You can activate this lint
+    /// ### Why is this bad?
+    /// Possibly surprising results. You can activate this lint
     /// as a one-time check to see where numerical wrapping can arise.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// let y: i8 = -1;
     /// y as u128; // will return 18446744073709551615
@@ -66,17 +66,17 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for casts between numerical types that may
+    /// ### What it does
+    /// Checks for casts between numerical types that may
     /// truncate large values. This is expected behavior, so the cast is `Allow` by
     /// default.
     ///
-    /// **Why is this bad?** In some problem domains, it is good practice to avoid
+    /// ### Why is this bad?
+    /// In some problem domains, it is good practice to avoid
     /// truncation. This lint can be activated to help assess where additional
     /// checks could be beneficial.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// fn as_u8(x: u64) -> u8 {
     ///     x as u8
@@ -88,20 +88,20 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for casts from an unsigned type to a signed type of
+    /// ### What it does
+    /// Checks for casts from an unsigned type to a signed type of
     /// the same size. Performing such a cast is a 'no-op' for the compiler,
     /// i.e., nothing is changed at the bit level, and the binary representation of
     /// the value is reinterpreted. This can cause wrapping if the value is too big
     /// for the target signed type. However, the cast works as defined, so this lint
     /// is `Allow` by default.
     ///
-    /// **Why is this bad?** While such a cast is not bad in itself, the results can
+    /// ### Why is this bad?
+    /// While such a cast is not bad in itself, the results can
     /// be surprising when this is not the intended behavior, as demonstrated by the
     /// example below.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// u32::MAX as i32; // will yield a value of `-1`
     /// ```
@@ -111,19 +111,19 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for casts between numerical types that may
+    /// ### What it does
+    /// Checks for casts between numerical types that may
     /// be replaced by safe conversion functions.
     ///
-    /// **Why is this bad?** Rust's `as` keyword will perform many kinds of
+    /// ### Why is this bad?
+    /// Rust's `as` keyword will perform many kinds of
     /// conversions, including silently lossy conversions. Conversion functions such
     /// as `i32::from` will only perform lossless conversions. Using the conversion
     /// functions prevents conversions from turning into silent lossy conversions if
     /// the types of the input expressions ever change, and make it easier for
     /// people reading the code to know that the conversion is lossless.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// fn as_u64(x: u8) -> u64 {
     ///     x as u64
@@ -143,14 +143,14 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for casts to the same type, casts of int literals to integer types
+    /// ### What it does
+    /// Checks for casts to the same type, casts of int literals to integer types
     /// and casts of float literals to float types.
     ///
-    /// **Why is this bad?** It's just unnecessary.
-    ///
-    /// **Known problems:** None.
+    /// ### Why is this bad?
+    /// It's just unnecessary.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// let _ = 2i32 as i32;
     /// let _ = 0.5 as f32;
@@ -168,17 +168,20 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for casts, using `as` or `pointer::cast`,
+    /// ### What it does
+    /// Checks for casts, using `as` or `pointer::cast`,
     /// from a less-strictly-aligned pointer to a more-strictly-aligned pointer
     ///
-    /// **Why is this bad?** Dereferencing the resulting pointer may be undefined
+    /// ### Why is this bad?
+    /// Dereferencing the resulting pointer may be undefined
     /// behavior.
     ///
-    /// **Known problems:** Using `std::ptr::read_unaligned` and `std::ptr::write_unaligned` or similar
+    /// ### Known problems
+    /// Using `std::ptr::read_unaligned` and `std::ptr::write_unaligned` or similar
     /// on the resulting pointer is fine. Is over-zealous: Casts with manual alignment checks or casts like
     /// u64-> u8 -> u16 can be fine. Miri is able to do a more in-depth analysis.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// let _ = (&1u8 as *const u8) as *const u16;
     /// let _ = (&mut 1u8 as *mut u8) as *mut u16;
@@ -192,9 +195,10 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for casts of function pointers to something other than usize
+    /// ### What it does
+    /// Checks for casts of function pointers to something other than usize
     ///
-    /// **Why is this bad?**
+    /// ### Why is this bad?
     /// Casting a function pointer to anything other than usize/isize is not portable across
     /// architectures, because you end up losing bits if the target type is too small or end up with a
     /// bunch of extra bits that waste space and add more instructions to the final binary than
@@ -202,8 +206,7 @@ declare_clippy_lint! {
     ///
     /// Casting to isize also doesn't make sense since there are no signed addresses.
     ///
-    /// **Example**
-    ///
+    /// ### Example
     /// ```rust
     /// // Bad
     /// fn fun() -> i32 { 1 }
@@ -219,16 +222,16 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for casts of a function pointer to a numeric type not wide enough to
+    /// ### What it does
+    /// Checks for casts of a function pointer to a numeric type not wide enough to
     /// store address.
     ///
-    /// **Why is this bad?**
+    /// ### Why is this bad?
     /// Such a cast discards some bits of the function's address. If this is intended, it would be more
     /// clearly expressed by casting to usize first, then casting the usize to the intended type (with
     /// a comment) to perform the truncation.
     ///
-    /// **Example**
-    ///
+    /// ### Example
     /// ```rust
     /// // Bad
     /// fn fn1() -> i16 {
@@ -249,15 +252,15 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for casts of `&T` to `&mut T` anywhere in the code.
+    /// ### What it does
+    /// Checks for casts of `&T` to `&mut T` anywhere in the code.
     ///
-    /// **Why is this bad?** It’s basically guaranteed to be undefined behaviour.
+    /// ### Why is this bad?
+    /// It’s basically guaranteed to be undefined behaviour.
     /// `UnsafeCell` is the only way to obtain aliasable data that is considered
     /// mutable.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust,ignore
     /// fn x(r: &i32) {
     ///     unsafe {
@@ -283,18 +286,18 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for expressions where a character literal is cast
+    /// ### What it does
+    /// Checks for expressions where a character literal is cast
     /// to `u8` and suggests using a byte literal instead.
     ///
-    /// **Why is this bad?** In general, casting values to smaller types is
+    /// ### Why is this bad?
+    /// In general, casting values to smaller types is
     /// error-prone and should be avoided where possible. In the particular case of
     /// converting a character literal to u8, it is easy to avoid by just using a
     /// byte literal instead. As an added bonus, `b'a'` is even slightly shorter
     /// than `'a' as u8`.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust,ignore
     /// 'x' as u8
     /// ```
@@ -310,18 +313,15 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:**
+    /// ### What it does
     /// Checks for `as` casts between raw pointers without changing its mutability,
     /// namely `*const T` to `*const U` and `*mut T` to `*mut U`.
     ///
-    /// **Why is this bad?**
+    /// ### Why is this bad?
     /// Though `as` casts between raw pointers is not terrible, `pointer::cast` is safer because
     /// it cannot accidentally change the pointer's mutability nor cast the pointer to other types like `usize`.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust
     /// let ptr: *const u32 = &42_u32;
     /// let mut_ptr: *mut u32 = &mut 42_u32;
diff --git a/clippy_lints/src/checked_conversions.rs b/clippy_lints/src/checked_conversions.rs
index 8d3123e1ec8ee..842bbf006cca9 100644
--- a/clippy_lints/src/checked_conversions.rs
+++ b/clippy_lints/src/checked_conversions.rs
@@ -13,13 +13,13 @@ use rustc_semver::RustcVersion;
 use rustc_session::{declare_tool_lint, impl_lint_pass};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for explicit bounds checking when casting.
+    /// ### What it does
+    /// Checks for explicit bounds checking when casting.
     ///
-    /// **Why is this bad?** Reduces the readability of statements & is error prone.
+    /// ### Why is this bad?
+    /// Reduces the readability of statements & is error prone.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # let foo: u32 = 5;
     /// # let _ =
diff --git a/clippy_lints/src/cognitive_complexity.rs b/clippy_lints/src/cognitive_complexity.rs
index f62c6a9c3251c..96c30d57ee198 100644
--- a/clippy_lints/src/cognitive_complexity.rs
+++ b/clippy_lints/src/cognitive_complexity.rs
@@ -14,15 +14,19 @@ use rustc_span::source_map::Span;
 use rustc_span::{sym, BytePos};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for methods with high cognitive complexity.
+    /// ### What it does
+    /// Checks for methods with high cognitive complexity.
     ///
-    /// **Why is this bad?** Methods of high cognitive complexity tend to be hard to
+    /// ### Why is this bad?
+    /// Methods of high cognitive complexity tend to be hard to
     /// both read and maintain. Also LLVM will tend to optimize small methods better.
     ///
-    /// **Known problems:** Sometimes it's hard to find a way to reduce the
+    /// ### Known problems
+    /// Sometimes it's hard to find a way to reduce the
     /// complexity.
     ///
-    /// **Example:** No. You'll see it when you get the warning.
+    /// ### Example
+    /// No. You'll see it when you get the warning.
     pub COGNITIVE_COMPLEXITY,
     nursery,
     "functions that should be split up into multiple functions"
diff --git a/clippy_lints/src/collapsible_if.rs b/clippy_lints/src/collapsible_if.rs
index 6e95073823908..4aa8798071568 100644
--- a/clippy_lints/src/collapsible_if.rs
+++ b/clippy_lints/src/collapsible_if.rs
@@ -22,15 +22,15 @@ use rustc_lint::{EarlyContext, EarlyLintPass};
 use rustc_session::{declare_lint_pass, declare_tool_lint};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for nested `if` statements which can be collapsed
+    /// ### What it does
+    /// Checks for nested `if` statements which can be collapsed
     /// by `&&`-combining their conditions.
     ///
-    /// **Why is this bad?** Each `if`-statement adds one level of nesting, which
+    /// ### Why is this bad?
+    /// Each `if`-statement adds one level of nesting, which
     /// makes code look more complex than it really is.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust,ignore
     /// if x {
     ///     if y {
@@ -53,15 +53,15 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for collapsible `else { if ... }` expressions
+    /// ### What it does
+    /// Checks for collapsible `else { if ... }` expressions
     /// that can be collapsed to `else if ...`.
     ///
-    /// **Why is this bad?** Each `if`-statement adds one level of nesting, which
+    /// ### Why is this bad?
+    /// Each `if`-statement adds one level of nesting, which
     /// makes code look more complex than it really is.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust,ignore
     ///
     /// if x {
diff --git a/clippy_lints/src/collapsible_match.rs b/clippy_lints/src/collapsible_match.rs
index a6c3a5b0e83c4..a403a9846babd 100644
--- a/clippy_lints/src/collapsible_match.rs
+++ b/clippy_lints/src/collapsible_match.rs
@@ -9,18 +9,17 @@ use rustc_session::{declare_lint_pass, declare_tool_lint};
 use rustc_span::{MultiSpan, Span};
 
 declare_clippy_lint! {
-    /// **What it does:** Finds nested `match` or `if let` expressions where the patterns may be "collapsed" together
+    /// ### What it does
+    /// Finds nested `match` or `if let` expressions where the patterns may be "collapsed" together
     /// without adding any branches.
     ///
     /// Note that this lint is not intended to find _all_ cases where nested match patterns can be merged, but only
     /// cases where merging would most likely make the code more readable.
     ///
-    /// **Why is this bad?** It is unnecessarily verbose and complex.
-    ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Why is this bad?
+    /// It is unnecessarily verbose and complex.
     ///
+    /// ### Example
     /// ```rust
     /// fn func(opt: Option<Result<u64, String>>) {
     ///     let n = match opt {
diff --git a/clippy_lints/src/comparison_chain.rs b/clippy_lints/src/comparison_chain.rs
index b6999bef6e726..597a3c67024e5 100644
--- a/clippy_lints/src/comparison_chain.rs
+++ b/clippy_lints/src/comparison_chain.rs
@@ -6,16 +6,19 @@ use rustc_lint::{LateContext, LateLintPass};
 use rustc_session::{declare_lint_pass, declare_tool_lint};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks comparison chains written with `if` that can be
+    /// ### What it does
+    /// Checks comparison chains written with `if` that can be
     /// rewritten with `match` and `cmp`.
     ///
-    /// **Why is this bad?** `if` is not guaranteed to be exhaustive and conditionals can get
+    /// ### Why is this bad?
+    /// `if` is not guaranteed to be exhaustive and conditionals can get
     /// repetitive
     ///
-    /// **Known problems:** The match statement may be slower due to the compiler
+    /// ### Known problems
+    /// The match statement may be slower due to the compiler
     /// not inlining the call to cmp. See issue [#5354](https://github.com/rust-lang/rust-clippy/issues/5354)
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust,ignore
     /// # fn a() {}
     /// # fn b() {}
diff --git a/clippy_lints/src/copies.rs b/clippy_lints/src/copies.rs
index 9cbcde597686e..2dcd55457993c 100644
--- a/clippy_lints/src/copies.rs
+++ b/clippy_lints/src/copies.rs
@@ -16,13 +16,13 @@ use rustc_span::{source_map::Span, symbol::Symbol, BytePos};
 use std::borrow::Cow;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for consecutive `if`s with the same condition.
+    /// ### What it does
+    /// Checks for consecutive `if`s with the same condition.
     ///
-    /// **Why is this bad?** This is probably a copy & paste error.
+    /// ### Why is this bad?
+    /// This is probably a copy & paste error.
     ///
-    /// **Known problems:** Hopefully none.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```ignore
     /// if a == b {
     ///     …
@@ -47,15 +47,15 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for consecutive `if`s with the same function call.
+    /// ### What it does
+    /// Checks for consecutive `if`s with the same function call.
     ///
-    /// **Why is this bad?** This is probably a copy & paste error.
+    /// ### Why is this bad?
+    /// This is probably a copy & paste error.
     /// Despite the fact that function can have side effects and `if` works as
     /// intended, such an approach is implicit and can be considered a "code smell".
     ///
-    /// **Known problems:** Hopefully none.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```ignore
     /// if foo() == bar {
     ///     …
@@ -94,14 +94,14 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for `if/else` with the same body as the *then* part
+    /// ### What it does
+    /// Checks for `if/else` with the same body as the *then* part
     /// and the *else* part.
     ///
-    /// **Why is this bad?** This is probably a copy & paste error.
-    ///
-    /// **Known problems:** Hopefully none.
+    /// ### Why is this bad?
+    /// This is probably a copy & paste error.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```ignore
     /// let foo = if … {
     ///     42
@@ -115,17 +115,19 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks if the `if` and `else` block contain shared code that can be
+    /// ### What it does
+    /// Checks if the `if` and `else` block contain shared code that can be
     /// moved out of the blocks.
     ///
-    /// **Why is this bad?** Duplicate code is less maintainable.
+    /// ### Why is this bad?
+    /// Duplicate code is less maintainable.
     ///
-    /// **Known problems:**
+    /// ### Known problems
     /// * The lint doesn't check if the moved expressions modify values that are beeing used in
     ///   the if condition. The suggestion can in that case modify the behavior of the program.
     ///   See [rust-clippy#7452](https://github.com/rust-lang/rust-clippy/issues/7452)
     ///
-    /// **Example:**
+    /// ### Example
     /// ```ignore
     /// let foo = if … {
     ///     println!("Hello World");
diff --git a/clippy_lints/src/copy_iterator.rs b/clippy_lints/src/copy_iterator.rs
index 35079c6bedc02..c2e9e8b3ab7f3 100644
--- a/clippy_lints/src/copy_iterator.rs
+++ b/clippy_lints/src/copy_iterator.rs
@@ -8,15 +8,15 @@ use rustc_span::sym;
 use if_chain::if_chain;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for types that implement `Copy` as well as
+    /// ### What it does
+    /// Checks for types that implement `Copy` as well as
     /// `Iterator`.
     ///
-    /// **Why is this bad?** Implicit copies can be confusing when working with
+    /// ### Why is this bad?
+    /// Implicit copies can be confusing when working with
     /// iterator combinators.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust,ignore
     /// #[derive(Copy, Clone)]
     /// struct Countdown(u8);
diff --git a/clippy_lints/src/create_dir.rs b/clippy_lints/src/create_dir.rs
index 7b5cce6462a43..e4ee27724831d 100644
--- a/clippy_lints/src/create_dir.rs
+++ b/clippy_lints/src/create_dir.rs
@@ -8,13 +8,13 @@ use rustc_lint::{LateContext, LateLintPass};
 use rustc_session::{declare_lint_pass, declare_tool_lint};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks usage of `std::fs::create_dir` and suggest using `std::fs::create_dir_all` instead.
+    /// ### What it does
+    /// Checks usage of `std::fs::create_dir` and suggest using `std::fs::create_dir_all` instead.
     ///
-    /// **Why is this bad?** Sometimes `std::fs::create_dir` is mistakenly chosen over `std::fs::create_dir_all`.
+    /// ### Why is this bad?
+    /// Sometimes `std::fs::create_dir` is mistakenly chosen over `std::fs::create_dir_all`.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     ///
     /// ```rust
     /// std::fs::create_dir("foo");
diff --git a/clippy_lints/src/dbg_macro.rs b/clippy_lints/src/dbg_macro.rs
index 286cc7e223efb..bab4a696f831e 100644
--- a/clippy_lints/src/dbg_macro.rs
+++ b/clippy_lints/src/dbg_macro.rs
@@ -8,14 +8,14 @@ use rustc_session::{declare_lint_pass, declare_tool_lint};
 use rustc_span::source_map::Span;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for usage of dbg!() macro.
+    /// ### What it does
+    /// Checks for usage of dbg!() macro.
     ///
-    /// **Why is this bad?** `dbg!` macro is intended as a debugging tool. It
+    /// ### Why is this bad?
+    /// `dbg!` macro is intended as a debugging tool. It
     /// should not be in version control.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust,ignore
     /// // Bad
     /// dbg!(true)
diff --git a/clippy_lints/src/default.rs b/clippy_lints/src/default.rs
index 947479db8f5d7..db8f2171348f7 100644
--- a/clippy_lints/src/default.rs
+++ b/clippy_lints/src/default.rs
@@ -13,14 +13,14 @@ use rustc_span::symbol::{Ident, Symbol};
 use rustc_span::Span;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for literal calls to `Default::default()`.
+    /// ### What it does
+    /// Checks for literal calls to `Default::default()`.
     ///
-    /// **Why is this bad?** It's more clear to the reader to use the name of the type whose default is
+    /// ### Why is this bad?
+    /// It's more clear to the reader to use the name of the type whose default is
     /// being gotten than the generic `Default`.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// // Bad
     /// let s: String = Default::default();
@@ -34,14 +34,17 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for immediate reassignment of fields initialized
+    /// ### What it does
+    /// Checks for immediate reassignment of fields initialized
     /// with Default::default().
     ///
-    /// **Why is this bad?**It's more idiomatic to use the [functional update syntax](https://doc.rust-lang.org/reference/expressions/struct-expr.html#functional-update-syntax).
+    /// ### Why is this bad?
+    ///It's more idiomatic to use the [functional update syntax](https://doc.rust-lang.org/reference/expressions/struct-expr.html#functional-update-syntax).
     ///
-    /// **Known problems:** Assignments to patterns that are of tuple type are not linted.
+    /// ### Known problems
+    /// Assignments to patterns that are of tuple type are not linted.
     ///
-    /// **Example:**
+    /// ### Example
     /// Bad:
     /// ```
     /// # #[derive(Default)]
diff --git a/clippy_lints/src/default_numeric_fallback.rs b/clippy_lints/src/default_numeric_fallback.rs
index e719a1b0abf87..3f1b7ea6214d4 100644
--- a/clippy_lints/src/default_numeric_fallback.rs
+++ b/clippy_lints/src/default_numeric_fallback.rs
@@ -18,7 +18,8 @@ use rustc_session::{declare_lint_pass, declare_tool_lint};
 use std::iter;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for usage of unconstrained numeric literals which may cause default numeric fallback in type
+    /// ### What it does
+    /// Checks for usage of unconstrained numeric literals which may cause default numeric fallback in type
     /// inference.
     ///
     /// Default numeric fallback means that if numeric types have not yet been bound to concrete
@@ -27,12 +28,14 @@ declare_clippy_lint! {
     ///
     /// See [RFC0212](https://github.com/rust-lang/rfcs/blob/master/text/0212-restore-int-fallback.md) for more information about the fallback.
     ///
-    /// **Why is this bad?** For those who are very careful about types, default numeric fallback
+    /// ### Why is this bad?
+    /// For those who are very careful about types, default numeric fallback
     /// can be a pitfall that cause unexpected runtime behavior.
     ///
-    /// **Known problems:** This lint can only be allowed at the function level or above.
+    /// ### Known problems
+    /// This lint can only be allowed at the function level or above.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// let i = 10;
     /// let f = 1.23;
diff --git a/clippy_lints/src/deprecated_lints.rs b/clippy_lints/src/deprecated_lints.rs
index 2933fbc93418a..c604516742ce5 100644
--- a/clippy_lints/src/deprecated_lints.rs
+++ b/clippy_lints/src/deprecated_lints.rs
@@ -12,27 +12,33 @@ macro_rules! declare_deprecated_lint {
 }
 
 declare_deprecated_lint! {
-    /// **What it does:** Nothing. This lint has been deprecated.
+    /// ### What it does
+    /// Nothing. This lint has been deprecated.
     ///
-    /// **Deprecation reason:** This used to check for `assert!(a == b)` and recommend
+    /// ### Deprecation reason
+    /// This used to check for `assert!(a == b)` and recommend
     /// replacement with `assert_eq!(a, b)`, but this is no longer needed after RFC 2011.
     pub SHOULD_ASSERT_EQ,
     "`assert!()` will be more flexible with RFC 2011"
 }
 
 declare_deprecated_lint! {
-    /// **What it does:** Nothing. This lint has been deprecated.
+    /// ### What it does
+    /// Nothing. This lint has been deprecated.
     ///
-    /// **Deprecation reason:** This used to check for `Vec::extend`, which was slower than
+    /// ### Deprecation reason
+    /// This used to check for `Vec::extend`, which was slower than
     /// `Vec::extend_from_slice`. Thanks to specialization, this is no longer true.
     pub EXTEND_FROM_SLICE,
     "`.extend_from_slice(_)` is a faster way to extend a Vec by a slice"
 }
 
 declare_deprecated_lint! {
-    /// **What it does:** Nothing. This lint has been deprecated.
+    /// ### What it does
+    /// Nothing. This lint has been deprecated.
     ///
-    /// **Deprecation reason:** `Range::step_by(0)` used to be linted since it's
+    /// ### Deprecation reason
+    /// `Range::step_by(0)` used to be linted since it's
     /// an infinite iterator, which is better expressed by `iter::repeat`,
     /// but the method has been removed for `Iterator::step_by` which panics
     /// if given a zero
@@ -41,27 +47,33 @@ declare_deprecated_lint! {
 }
 
 declare_deprecated_lint! {
-    /// **What it does:** Nothing. This lint has been deprecated.
+    /// ### What it does
+    /// Nothing. This lint has been deprecated.
     ///
-    /// **Deprecation reason:** This used to check for `Vec::as_slice`, which was unstable with good
+    /// ### Deprecation reason
+    /// This used to check for `Vec::as_slice`, which was unstable with good
     /// stable alternatives. `Vec::as_slice` has now been stabilized.
     pub UNSTABLE_AS_SLICE,
     "`Vec::as_slice` has been stabilized in 1.7"
 }
 
 declare_deprecated_lint! {
-    /// **What it does:** Nothing. This lint has been deprecated.
+    /// ### What it does
+    /// Nothing. This lint has been deprecated.
     ///
-    /// **Deprecation reason:** This used to check for `Vec::as_mut_slice`, which was unstable with good
+    /// ### Deprecation reason
+    /// This used to check for `Vec::as_mut_slice`, which was unstable with good
     /// stable alternatives. `Vec::as_mut_slice` has now been stabilized.
     pub UNSTABLE_AS_MUT_SLICE,
     "`Vec::as_mut_slice` has been stabilized in 1.7"
 }
 
 declare_deprecated_lint! {
-    /// **What it does:** Nothing. This lint has been deprecated.
+    /// ### What it does
+    /// Nothing. This lint has been deprecated.
     ///
-    /// **Deprecation reason:** This lint should never have applied to non-pointer types, as transmuting
+    /// ### Deprecation reason
+    /// This lint should never have applied to non-pointer types, as transmuting
     /// between non-pointer types of differing alignment is well-defined behavior (it's semantically
     /// equivalent to a memcpy). This lint has thus been refactored into two separate lints:
     /// cast_ptr_alignment and transmute_ptr_to_ptr.
@@ -70,9 +82,11 @@ declare_deprecated_lint! {
 }
 
 declare_deprecated_lint! {
-    /// **What it does:** Nothing. This lint has been deprecated.
+    /// ### What it does
+    /// Nothing. This lint has been deprecated.
     ///
-    /// **Deprecation reason:** This lint is too subjective, not having a good reason for being in clippy.
+    /// ### Deprecation reason
+    /// This lint is too subjective, not having a good reason for being in clippy.
     /// Additionally, compound assignment operators may be overloaded separately from their non-assigning
     /// counterparts, so this lint may suggest a change in behavior or the code may not compile.
     pub ASSIGN_OPS,
@@ -80,9 +94,11 @@ declare_deprecated_lint! {
 }
 
 declare_deprecated_lint! {
-    /// **What it does:** Nothing. This lint has been deprecated.
+    /// ### What it does
+    /// Nothing. This lint has been deprecated.
     ///
-    /// **Deprecation reason:** The original rule will only lint for `if let`. After
+    /// ### Deprecation reason
+    /// The original rule will only lint for `if let`. After
     /// making it support to lint `match`, naming as `if let` is not suitable for it.
     /// So, this lint is deprecated.
     pub IF_LET_REDUNDANT_PATTERN_MATCHING,
@@ -90,9 +106,11 @@ declare_deprecated_lint! {
 }
 
 declare_deprecated_lint! {
-    /// **What it does:** Nothing. This lint has been deprecated.
+    /// ### What it does
+    /// Nothing. This lint has been deprecated.
     ///
-    /// **Deprecation reason:** This lint used to suggest replacing `let mut vec =
+    /// ### Deprecation reason
+    /// This lint used to suggest replacing `let mut vec =
     /// Vec::with_capacity(n); vec.set_len(n);` with `let vec = vec![0; n];`. The
     /// replacement has very different performance characteristics so the lint is
     /// deprecated.
@@ -101,51 +119,63 @@ declare_deprecated_lint! {
 }
 
 declare_deprecated_lint! {
-    /// **What it does:** Nothing. This lint has been deprecated.
+    /// ### What it does
+    /// Nothing. This lint has been deprecated.
     ///
-    /// **Deprecation reason:** This lint has been superseded by #[must_use] in rustc.
+    /// ### Deprecation reason
+    /// This lint has been superseded by #[must_use] in rustc.
     pub UNUSED_COLLECT,
     "`collect` has been marked as #[must_use] in rustc and that covers all cases of this lint"
 }
 
 declare_deprecated_lint! {
-    /// **What it does:** Nothing. This lint has been deprecated.
+    /// ### What it does
+    /// Nothing. This lint has been deprecated.
     ///
-    /// **Deprecation reason:** Associated-constants are now preferred.
+    /// ### Deprecation reason
+    /// Associated-constants are now preferred.
     pub REPLACE_CONSTS,
     "associated-constants `MIN`/`MAX` of integers are preferred to `{min,max}_value()` and module constants"
 }
 
 declare_deprecated_lint! {
-    /// **What it does:** Nothing. This lint has been deprecated.
+    /// ### What it does
+    /// Nothing. This lint has been deprecated.
     ///
-    /// **Deprecation reason:** The regex! macro does not exist anymore.
+    /// ### Deprecation reason
+    /// The regex! macro does not exist anymore.
     pub REGEX_MACRO,
     "the regex! macro has been removed from the regex crate in 2018"
 }
 
 declare_deprecated_lint! {
-    /// **What it does:** Nothing. This lint has been deprecated.
+    /// ### What it does
+    /// Nothing. This lint has been deprecated.
     ///
-    /// **Deprecation reason:** This lint has been replaced by `manual_find_map`, a
+    /// ### Deprecation reason
+    /// This lint has been replaced by `manual_find_map`, a
     /// more specific lint.
     pub FIND_MAP,
     "this lint has been replaced by `manual_find_map`, a more specific lint"
 }
 
 declare_deprecated_lint! {
-    /// **What it does:** Nothing. This lint has been deprecated.
+    /// ### What it does
+    /// Nothing. This lint has been deprecated.
     ///
-    /// **Deprecation reason:** This lint has been replaced by `manual_filter_map`, a
+    /// ### Deprecation reason
+    /// This lint has been replaced by `manual_filter_map`, a
     /// more specific lint.
     pub FILTER_MAP,
     "this lint has been replaced by `manual_filter_map`, a more specific lint"
 }
 
 declare_deprecated_lint! {
-    /// **What it does:** Nothing. This lint has been deprecated.
+    /// ### What it does
+    /// Nothing. This lint has been deprecated.
     ///
-    /// **Deprecation reason:** The `avoid_breaking_exported_api` config option was added, which
+    /// ### Deprecation reason
+    /// The `avoid_breaking_exported_api` config option was added, which
     /// enables the `enum_variant_names` lint for public items.
     /// ```
     pub PUB_ENUM_VARIANT_NAMES,
@@ -153,9 +183,11 @@ declare_deprecated_lint! {
 }
 
 declare_deprecated_lint! {
-    /// **What it does:** Nothing. This lint has been deprecated.
+    /// ### What it does
+    /// Nothing. This lint has been deprecated.
     ///
-    /// **Deprecation reason:** The `avoid_breaking_exported_api` config option was added, which
+    /// ### Deprecation reason
+    /// The `avoid_breaking_exported_api` config option was added, which
     /// enables the `wrong_self_conversion` lint for public items.
     pub WRONG_PUB_SELF_CONVENTION,
     "set the `avoid-breaking-exported-api` config option to `false` to enable the `wrong_self_convention` lint for public items"
diff --git a/clippy_lints/src/dereference.rs b/clippy_lints/src/dereference.rs
index 682003f9c2c4c..ded7001ad8c86 100644
--- a/clippy_lints/src/dereference.rs
+++ b/clippy_lints/src/dereference.rs
@@ -11,12 +11,14 @@ use rustc_session::{declare_tool_lint, impl_lint_pass};
 use rustc_span::{symbol::sym, Span};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for explicit `deref()` or `deref_mut()` method calls.
+    /// ### What it does
+    /// Checks for explicit `deref()` or `deref_mut()` method calls.
     ///
-    /// **Why is this bad?** Dereferencing by `&*x` or `&mut *x` is clearer and more concise,
+    /// ### Why is this bad?
+    /// Dereferencing by `&*x` or `&mut *x` is clearer and more concise,
     /// when not part of a method chain.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// use std::ops::Deref;
     /// let a: &mut String = &mut String::from("foo");
diff --git a/clippy_lints/src/derive.rs b/clippy_lints/src/derive.rs
index 7aafaf7138301..dcfa5253f8341 100644
--- a/clippy_lints/src/derive.rs
+++ b/clippy_lints/src/derive.rs
@@ -15,10 +15,12 @@ use rustc_session::{declare_lint_pass, declare_tool_lint};
 use rustc_span::source_map::Span;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for deriving `Hash` but implementing `PartialEq`
+    /// ### What it does
+    /// Checks for deriving `Hash` but implementing `PartialEq`
     /// explicitly or vice versa.
     ///
-    /// **Why is this bad?** The implementation of these traits must agree (for
+    /// ### Why is this bad?
+    /// The implementation of these traits must agree (for
     /// example for use with `HashMap`) so it’s probably a bad idea to use a
     /// default-generated `Hash` implementation with an explicitly defined
     /// `PartialEq`. In particular, the following must hold for any type:
@@ -27,9 +29,7 @@ declare_clippy_lint! {
     /// k1 == k2 ⇒ hash(k1) == hash(k2)
     /// ```
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```ignore
     /// #[derive(Hash)]
     /// struct Foo;
@@ -44,10 +44,12 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for deriving `Ord` but implementing `PartialOrd`
+    /// ### What it does
+    /// Checks for deriving `Ord` but implementing `PartialOrd`
     /// explicitly or vice versa.
     ///
-    /// **Why is this bad?** The implementation of these traits must agree (for
+    /// ### Why is this bad?
+    /// The implementation of these traits must agree (for
     /// example for use with `sort`) so it’s probably a bad idea to use a
     /// default-generated `Ord` implementation with an explicitly defined
     /// `PartialOrd`. In particular, the following must hold for any type
@@ -57,10 +59,7 @@ declare_clippy_lint! {
     /// k1.cmp(&k2) == k1.partial_cmp(&k2).unwrap()
     /// ```
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust,ignore
     /// #[derive(Ord, PartialEq, Eq)]
     /// struct Foo;
@@ -95,18 +94,21 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for explicit `Clone` implementations for `Copy`
+    /// ### What it does
+    /// Checks for explicit `Clone` implementations for `Copy`
     /// types.
     ///
-    /// **Why is this bad?** To avoid surprising behaviour, these traits should
+    /// ### Why is this bad?
+    /// To avoid surprising behaviour, these traits should
     /// agree and the behaviour of `Copy` cannot be overridden. In almost all
     /// situations a `Copy` type should have a `Clone` implementation that does
     /// nothing more than copy the object, which is what `#[derive(Copy, Clone)]`
     /// gets you.
     ///
-    /// **Known problems:** Bounds of generic types are sometimes wrong: https://github.com/rust-lang/rust/issues/26925
+    /// ### Known problems
+    /// Bounds of generic types are sometimes wrong: https://github.com/rust-lang/rust/issues/26925
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust,ignore
     /// #[derive(Copy)]
     /// struct Foo;
@@ -121,16 +123,15 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for deriving `serde::Deserialize` on a type that
+    /// ### What it does
+    /// Checks for deriving `serde::Deserialize` on a type that
     /// has methods using `unsafe`.
     ///
-    /// **Why is this bad?** Deriving `serde::Deserialize` will create a constructor
+    /// ### Why is this bad?
+    /// Deriving `serde::Deserialize` will create a constructor
     /// that may violate invariants hold by another constructor.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust,ignore
     /// use serde::Deserialize;
     ///
diff --git a/clippy_lints/src/disallowed_method.rs b/clippy_lints/src/disallowed_method.rs
index aa1a609afedc0..7069cb4198ca9 100644
--- a/clippy_lints/src/disallowed_method.rs
+++ b/clippy_lints/src/disallowed_method.rs
@@ -8,15 +8,14 @@ use rustc_session::{declare_tool_lint, impl_lint_pass};
 use rustc_span::Symbol;
 
 declare_clippy_lint! {
-    /// **What it does:** Denies the configured methods and functions in clippy.toml
+    /// ### What it does
+    /// Denies the configured methods and functions in clippy.toml
     ///
-    /// **Why is this bad?** Some methods are undesirable in certain contexts,
+    /// ### Why is this bad?
+    /// Some methods are undesirable in certain contexts,
     /// and it's beneficial to lint for them as needed.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// An example clippy.toml configuration:
     /// ```toml
     /// # clippy.toml
diff --git a/clippy_lints/src/disallowed_script_idents.rs b/clippy_lints/src/disallowed_script_idents.rs
index 12c525634c51d..6d38d30cd0bab 100644
--- a/clippy_lints/src/disallowed_script_idents.rs
+++ b/clippy_lints/src/disallowed_script_idents.rs
@@ -6,7 +6,8 @@ use rustc_session::{declare_tool_lint, impl_lint_pass};
 use unicode_script::{Script, UnicodeScript};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for usage of unicode scripts other than those explicitly allowed
+    /// ### What it does
+    /// Checks for usage of unicode scripts other than those explicitly allowed
     /// by the lint config.
     ///
     /// This lint doesn't take into account non-text scripts such as `Unknown` and `Linear_A`.
@@ -19,7 +20,8 @@ declare_clippy_lint! {
     /// [aliases]: http://www.unicode.org/reports/tr24/tr24-31.html#Script_Value_Aliases
     /// [supported_scripts]: https://www.unicode.org/iso15924/iso15924-codes.html
     ///
-    /// **Why is this bad?** It may be not desired to have many different scripts for
+    /// ### Why is this bad?
+    /// It may be not desired to have many different scripts for
     /// identifiers in the codebase.
     ///
     /// Note that if you only want to allow plain English, you might want to use
@@ -27,9 +29,7 @@ declare_clippy_lint! {
     ///
     /// [`non_ascii_idents`]: https://doc.rust-lang.org/rustc/lints/listing/allowed-by-default.html#non-ascii-idents
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// // Assuming that `clippy.toml` contains the following line:
     /// // allowed-locales = ["Latin", "Cyrillic"]
diff --git a/clippy_lints/src/disallowed_type.rs b/clippy_lints/src/disallowed_type.rs
index 7c76e2322c28f..e627168b93275 100644
--- a/clippy_lints/src/disallowed_type.rs
+++ b/clippy_lints/src/disallowed_type.rs
@@ -9,14 +9,13 @@ use rustc_session::{declare_tool_lint, impl_lint_pass};
 use rustc_span::{Span, Symbol};
 
 declare_clippy_lint! {
-    /// **What it does:** Denies the configured types in clippy.toml.
+    /// ### What it does
+    /// Denies the configured types in clippy.toml.
     ///
-    /// **Why is this bad?** Some types are undesirable in certain contexts.
-    ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Why is this bad?
+    /// Some types are undesirable in certain contexts.
     ///
+    /// ### Example:
     /// An example clippy.toml configuration:
     /// ```toml
     /// # clippy.toml
diff --git a/clippy_lints/src/doc.rs b/clippy_lints/src/doc.rs
index 0c19988a975a8..c39829fdc7aad 100644
--- a/clippy_lints/src/doc.rs
+++ b/clippy_lints/src/doc.rs
@@ -30,15 +30,18 @@ use std::thread;
 use url::Url;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for the presence of `_`, `::` or camel-case words
+    /// ### What it does
+    /// Checks for the presence of `_`, `::` or camel-case words
     /// outside ticks in documentation.
     ///
-    /// **Why is this bad?** *Rustdoc* supports markdown formatting, `_`, `::` and
+    /// ### Why is this bad?
+    /// *Rustdoc* supports markdown formatting, `_`, `::` and
     /// camel-case probably indicates some code which should be included between
     /// ticks. `_` can also be used for emphasis in markdown, this lint tries to
     /// consider that.
     ///
-    /// **Known problems:** Lots of bad docs won’t be fixed, what the lint checks
+    /// ### Known problems
+    /// Lots of bad docs won’t be fixed, what the lint checks
     /// for is limited, and there are still false positives. HTML elements and their
     /// content are not linted.
     ///
@@ -47,7 +50,7 @@ declare_clippy_lint! {
     /// `[`SmallVec<[T; INLINE_CAPACITY]>`]` and then [`SmallVec<[T; INLINE_CAPACITY]>`]: SmallVec
     /// would fail.
     ///
-    /// **Examples:**
+    /// ### Examples
     /// ```rust
     /// /// Do something with the foo_bar parameter. See also
     /// /// that::other::module::foo.
@@ -68,15 +71,15 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for the doc comments of publicly visible
+    /// ### What it does
+    /// Checks for the doc comments of publicly visible
     /// unsafe functions and warns if there is no `# Safety` section.
     ///
-    /// **Why is this bad?** Unsafe functions should document their safety
+    /// ### Why is this bad?
+    /// Unsafe functions should document their safety
     /// preconditions, so that users can be sure they are using them safely.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Examples:**
+    /// ### Examples
     /// ```rust
     ///# type Universe = ();
     /// /// This function should really be documented
@@ -102,16 +105,15 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks the doc comments of publicly visible functions that
+    /// ### What it does
+    /// Checks the doc comments of publicly visible functions that
     /// return a `Result` type and warns if there is no `# Errors` section.
     ///
-    /// **Why is this bad?** Documenting the type of errors that can be returned from a
+    /// ### Why is this bad?
+    /// Documenting the type of errors that can be returned from a
     /// function can help callers write code to handle the errors appropriately.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Examples:**
-    ///
+    /// ### Examples
     /// Since the following function returns a `Result` it has an `# Errors` section in
     /// its doc comment:
     ///
@@ -131,16 +133,15 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks the doc comments of publicly visible functions that
+    /// ### What it does
+    /// Checks the doc comments of publicly visible functions that
     /// may panic and warns if there is no `# Panics` section.
     ///
-    /// **Why is this bad?** Documenting the scenarios in which panicking occurs
+    /// ### Why is this bad?
+    /// Documenting the scenarios in which panicking occurs
     /// can help callers who do not want to panic to avoid those situations.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Examples:**
-    ///
+    /// ### Examples
     /// Since the following function may panic it has a `# Panics` section in
     /// its doc comment:
     ///
@@ -162,14 +163,14 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for `fn main() { .. }` in doctests
+    /// ### What it does
+    /// Checks for `fn main() { .. }` in doctests
     ///
-    /// **Why is this bad?** The test can be shorter (and likely more readable)
+    /// ### Why is this bad?
+    /// The test can be shorter (and likely more readable)
     /// if the `fn main()` is left implicit.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Examples:**
+    /// ### Examples
     /// ``````rust
     /// /// An example of a doctest with a `main()` function
     /// ///
diff --git a/clippy_lints/src/double_comparison.rs b/clippy_lints/src/double_comparison.rs
index 4966638cb1b96..6520bb91fafd2 100644
--- a/clippy_lints/src/double_comparison.rs
+++ b/clippy_lints/src/double_comparison.rs
@@ -10,14 +10,14 @@ use rustc_session::{declare_lint_pass, declare_tool_lint};
 use rustc_span::source_map::Span;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for double comparisons that could be simplified to a single expression.
+    /// ### What it does
+    /// Checks for double comparisons that could be simplified to a single expression.
     ///
     ///
-    /// **Why is this bad?** Readability.
+    /// ### Why is this bad?
+    /// Readability.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # let x = 1;
     /// # let y = 2;
diff --git a/clippy_lints/src/double_parens.rs b/clippy_lints/src/double_parens.rs
index e4e4a93b011fd..d0d87b6df9a2d 100644
--- a/clippy_lints/src/double_parens.rs
+++ b/clippy_lints/src/double_parens.rs
@@ -4,14 +4,14 @@ use rustc_lint::{EarlyContext, EarlyLintPass};
 use rustc_session::{declare_lint_pass, declare_tool_lint};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for unnecessary double parentheses.
+    /// ### What it does
+    /// Checks for unnecessary double parentheses.
     ///
-    /// **Why is this bad?** This makes code harder to read and might indicate a
+    /// ### Why is this bad?
+    /// This makes code harder to read and might indicate a
     /// mistake.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// // Bad
     /// fn simple_double_parens() -> i32 {
diff --git a/clippy_lints/src/drop_forget_ref.rs b/clippy_lints/src/drop_forget_ref.rs
index b5b29760636ba..0f3dc866afb6e 100644
--- a/clippy_lints/src/drop_forget_ref.rs
+++ b/clippy_lints/src/drop_forget_ref.rs
@@ -8,17 +8,17 @@ use rustc_middle::ty;
 use rustc_session::{declare_lint_pass, declare_tool_lint};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for calls to `std::mem::drop` with a reference
+    /// ### What it does
+    /// Checks for calls to `std::mem::drop` with a reference
     /// instead of an owned value.
     ///
-    /// **Why is this bad?** Calling `drop` on a reference will only drop the
+    /// ### Why is this bad?
+    /// Calling `drop` on a reference will only drop the
     /// reference itself, which is a no-op. It will not call the `drop` method (from
     /// the `Drop` trait implementation) on the underlying referenced value, which
     /// is likely what was intended.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```ignore
     /// let mut lock_guard = mutex.lock();
     /// std::mem::drop(&lock_guard) // Should have been drop(lock_guard), mutex
@@ -31,17 +31,17 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for calls to `std::mem::forget` with a reference
+    /// ### What it does
+    /// Checks for calls to `std::mem::forget` with a reference
     /// instead of an owned value.
     ///
-    /// **Why is this bad?** Calling `forget` on a reference will only forget the
+    /// ### Why is this bad?
+    /// Calling `forget` on a reference will only forget the
     /// reference itself, which is a no-op. It will not forget the underlying
     /// referenced
     /// value, which is likely what was intended.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// let x = Box::new(1);
     /// std::mem::forget(&x) // Should have been forget(x), x will still be dropped
@@ -52,16 +52,16 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for calls to `std::mem::drop` with a value
+    /// ### What it does
+    /// Checks for calls to `std::mem::drop` with a value
     /// that derives the Copy trait
     ///
-    /// **Why is this bad?** Calling `std::mem::drop` [does nothing for types that
+    /// ### Why is this bad?
+    /// Calling `std::mem::drop` [does nothing for types that
     /// implement Copy](https://doc.rust-lang.org/std/mem/fn.drop.html), since the
     /// value will be copied and moved into the function on invocation.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// let x: i32 = 42; // i32 implements Copy
     /// std::mem::drop(x) // A copy of x is passed to the function, leaving the
@@ -73,10 +73,12 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for calls to `std::mem::forget` with a value that
+    /// ### What it does
+    /// Checks for calls to `std::mem::forget` with a value that
     /// derives the Copy trait
     ///
-    /// **Why is this bad?** Calling `std::mem::forget` [does nothing for types that
+    /// ### Why is this bad?
+    /// Calling `std::mem::forget` [does nothing for types that
     /// implement Copy](https://doc.rust-lang.org/std/mem/fn.drop.html) since the
     /// value will be copied and moved into the function on invocation.
     ///
@@ -86,9 +88,7 @@ declare_clippy_lint! {
     /// there
     /// is nothing for `std::mem::forget` to ignore.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// let x: i32 = 42; // i32 implements Copy
     /// std::mem::forget(x) // A copy of x is passed to the function, leaving the
diff --git a/clippy_lints/src/duration_subsec.rs b/clippy_lints/src/duration_subsec.rs
index 94b09bf717372..3774de625213d 100644
--- a/clippy_lints/src/duration_subsec.rs
+++ b/clippy_lints/src/duration_subsec.rs
@@ -12,15 +12,15 @@ use clippy_utils::diagnostics::span_lint_and_sugg;
 use clippy_utils::paths;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for calculation of subsecond microseconds or milliseconds
+    /// ### What it does
+    /// Checks for calculation of subsecond microseconds or milliseconds
     /// from other `Duration` methods.
     ///
-    /// **Why is this bad?** It's more concise to call `Duration::subsec_micros()` or
+    /// ### Why is this bad?
+    /// It's more concise to call `Duration::subsec_micros()` or
     /// `Duration::subsec_millis()` than to calculate them.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # use std::time::Duration;
     /// let dur = Duration::new(5, 0);
diff --git a/clippy_lints/src/else_if_without_else.rs b/clippy_lints/src/else_if_without_else.rs
index 26984df953977..0541ac5eccca4 100644
--- a/clippy_lints/src/else_if_without_else.rs
+++ b/clippy_lints/src/else_if_without_else.rs
@@ -7,14 +7,14 @@ 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 if expressions with an `else if` branch,
+    /// ### What it does
+    /// Checks for usage of if expressions with an `else if` branch,
     /// but without a final `else` branch.
     ///
-    /// **Why is this bad?** Some coding guidelines require this (e.g., MISRA-C:2004 Rule 14.10).
+    /// ### Why is this bad?
+    /// Some coding guidelines require this (e.g., MISRA-C:2004 Rule 14.10).
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # fn a() {}
     /// # fn b() {}
diff --git a/clippy_lints/src/empty_enum.rs b/clippy_lints/src/empty_enum.rs
index c92984a98346d..3453c2da2784f 100644
--- a/clippy_lints/src/empty_enum.rs
+++ b/clippy_lints/src/empty_enum.rs
@@ -6,13 +6,15 @@ use rustc_lint::{LateContext, LateLintPass};
 use rustc_session::{declare_lint_pass, declare_tool_lint};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for `enum`s with no variants.
+    /// ### What it does
+    /// Checks for `enum`s with no variants.
     ///
     /// As of this writing, the `never_type` is still a
     /// nightly-only experimental API. Therefore, this lint is only triggered
     /// if the `never_type` is enabled.
     ///
-    /// **Why is this bad?** If you want to introduce a type which
+    /// ### Why is this bad?
+    /// If you want to introduce a type which
     /// can't be instantiated, you should use `!` (the primitive type "never"),
     /// or a wrapper around it, because `!` has more extensive
     /// compiler support (type inference, etc...) and wrappers
@@ -20,10 +22,7 @@ declare_clippy_lint! {
     /// For further information visit [never type documentation](https://doc.rust-lang.org/std/primitive.never.html)
     ///
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// Bad:
     /// ```rust
     /// enum Test {}
diff --git a/clippy_lints/src/entry.rs b/clippy_lints/src/entry.rs
index 2eb8b1422ed8a..e1d0d65edb1b9 100644
--- a/clippy_lints/src/entry.rs
+++ b/clippy_lints/src/entry.rs
@@ -16,12 +16,15 @@ use rustc_span::{Span, SyntaxContext, DUMMY_SP};
 use std::fmt::Write;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for uses of `contains_key` + `insert` on `HashMap`
+    /// ### What it does
+    /// Checks for uses of `contains_key` + `insert` on `HashMap`
     /// or `BTreeMap`.
     ///
-    /// **Why is this bad?** Using `entry` is more efficient.
+    /// ### Why is this bad?
+    /// Using `entry` is more efficient.
     ///
-    /// **Known problems:** The suggestion may have type inference errors in some cases. e.g.
+    /// ### Known problems
+    /// The suggestion may have type inference errors in some cases. e.g.
     /// ```rust
     /// let mut map = std::collections::HashMap::new();
     /// let _ = if !map.contains_key(&0) {
@@ -31,7 +34,7 @@ declare_clippy_lint! {
     /// };
     /// ```
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # use std::collections::HashMap;
     /// # let mut map = HashMap::new();
diff --git a/clippy_lints/src/enum_clike.rs b/clippy_lints/src/enum_clike.rs
index 021136ac5e019..a2c3c7a7b4920 100644
--- a/clippy_lints/src/enum_clike.rs
+++ b/clippy_lints/src/enum_clike.rs
@@ -11,15 +11,15 @@ use rustc_session::{declare_lint_pass, declare_tool_lint};
 use std::convert::TryFrom;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for C-like enumerations that are
+    /// ### What it does
+    /// Checks for C-like enumerations that are
     /// `repr(isize/usize)` and have values that don't fit into an `i32`.
     ///
-    /// **Why is this bad?** This will truncate the variant value on 32 bit
+    /// ### Why is this bad?
+    /// This will truncate the variant value on 32 bit
     /// architectures, but works fine on 64 bit.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # #[cfg(target_pointer_width = "64")]
     /// #[repr(usize)]
diff --git a/clippy_lints/src/enum_variants.rs b/clippy_lints/src/enum_variants.rs
index b1a105a51c106..32b95745b64d1 100644
--- a/clippy_lints/src/enum_variants.rs
+++ b/clippy_lints/src/enum_variants.rs
@@ -10,15 +10,15 @@ use rustc_span::source_map::Span;
 use rustc_span::symbol::Symbol;
 
 declare_clippy_lint! {
-    /// **What it does:** Detects enumeration variants that are prefixed or suffixed
+    /// ### What it does
+    /// Detects enumeration variants that are prefixed or suffixed
     /// by the same characters.
     ///
-    /// **Why is this bad?** Enumeration variant names should specify their variant,
+    /// ### Why is this bad?
+    /// Enumeration variant names should specify their variant,
     /// not repeat the enumeration name.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// enum Cake {
     ///     BlackForestCake,
@@ -40,14 +40,14 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Detects type names that are prefixed or suffixed by the
+    /// ### What it does
+    /// Detects type names that are prefixed or suffixed by the
     /// containing module's name.
     ///
-    /// **Why is this bad?** It requires the user to type the module name twice.
-    ///
-    /// **Known problems:** None.
+    /// ### Why is this bad?
+    /// It requires the user to type the module name twice.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// mod cake {
     ///     struct BlackForestCake;
@@ -65,10 +65,12 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for modules that have the same name as their
+    /// ### What it does
+    /// Checks for modules that have the same name as their
     /// parent module
     ///
-    /// **Why is this bad?** A typical beginner mistake is to have `mod foo;` and
+    /// ### Why is this bad?
+    /// A typical beginner mistake is to have `mod foo;` and
     /// again `mod foo { ..
     /// }` in `foo.rs`.
     /// The expectation is that items inside the inner `mod foo { .. }` are then
@@ -78,9 +80,7 @@ declare_clippy_lint! {
     /// If this is done on purpose, it would be better to choose a more
     /// representative module name.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```ignore
     /// // lib.rs
     /// mod foo;
diff --git a/clippy_lints/src/eq_op.rs b/clippy_lints/src/eq_op.rs
index d39cabfb2825b..51d5094e8c998 100644
--- a/clippy_lints/src/eq_op.rs
+++ b/clippy_lints/src/eq_op.rs
@@ -9,18 +9,21 @@ use rustc_lint::{LateContext, LateLintPass};
 use rustc_session::{declare_lint_pass, declare_tool_lint};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for equal operands to comparison, logical and
+    /// ### What it does
+    /// Checks for equal operands to comparison, logical and
     /// bitwise, difference and division binary operators (`==`, `>`, etc., `&&`,
     /// `||`, `&`, `|`, `^`, `-` and `/`).
     ///
-    /// **Why is this bad?** This is usually just a typo or a copy and paste error.
+    /// ### Why is this bad?
+    /// This is usually just a typo or a copy and paste error.
     ///
-    /// **Known problems:** False negatives: We had some false positives regarding
+    /// ### Known problems
+    /// False negatives: We had some false positives regarding
     /// calls (notably [racer](https://github.com/phildawes/racer) had one instance
     /// of `x.pop() && x.pop()`), so we removed matching any function or method
     /// calls. We may introduce a list of known pure functions in the future.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # let x = 1;
     /// if x + 1 == x + 1 {}
@@ -37,15 +40,18 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for arguments to `==` which have their address
+    /// ### What it does
+    /// Checks for arguments to `==` which have their address
     /// taken to satisfy a bound
     /// and suggests to dereference the other argument instead
     ///
-    /// **Why is this bad?** It is more idiomatic to dereference the other argument.
+    /// ### Why is this bad?
+    /// It is more idiomatic to dereference the other argument.
     ///
-    /// **Known problems:** None
+    /// ### Known problems
+    /// None
     ///
-    /// **Example:**
+    /// ### Example
     /// ```ignore
     /// // Bad
     /// &x == y
diff --git a/clippy_lints/src/erasing_op.rs b/clippy_lints/src/erasing_op.rs
index 4aa9c25b1b0b0..026d14d0ea265 100644
--- a/clippy_lints/src/erasing_op.rs
+++ b/clippy_lints/src/erasing_op.rs
@@ -6,15 +6,15 @@ use rustc_session::{declare_lint_pass, declare_tool_lint};
 use rustc_span::source_map::Span;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for erasing operations, e.g., `x * 0`.
+    /// ### What it does
+    /// Checks for erasing operations, e.g., `x * 0`.
     ///
-    /// **Why is this bad?** The whole expression can be replaced by zero.
+    /// ### Why is this bad?
+    /// The whole expression can be replaced by zero.
     /// This is most likely not the intended outcome and should probably be
     /// corrected
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// let x = 1;
     /// 0 / x;
diff --git a/clippy_lints/src/escape.rs b/clippy_lints/src/escape.rs
index 5f400d079da2f..8b0e9e6bc9b93 100644
--- a/clippy_lints/src/escape.rs
+++ b/clippy_lints/src/escape.rs
@@ -19,16 +19,16 @@ pub struct BoxedLocal {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for usage of `Box<T>` where an unboxed `T` would
+    /// ### What it does
+    /// Checks for usage of `Box<T>` where an unboxed `T` would
     /// work fine.
     ///
-    /// **Why is this bad?** This is an unnecessary allocation, and bad for
+    /// ### Why is this bad?
+    /// This is an unnecessary allocation, and bad for
     /// performance. It is only necessary to allocate if you wish to move the box
     /// into something.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # fn foo(bar: usize) {}
     /// // Bad
diff --git a/clippy_lints/src/eta_reduction.rs b/clippy_lints/src/eta_reduction.rs
index 667eb8eb283bb..192b69e18f90f 100644
--- a/clippy_lints/src/eta_reduction.rs
+++ b/clippy_lints/src/eta_reduction.rs
@@ -14,19 +14,22 @@ use rustc_middle::ty::{self, ClosureKind, Ty};
 use rustc_session::{declare_lint_pass, declare_tool_lint};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for closures which just call another function where
+    /// ### What it does
+    /// Checks for closures which just call another function where
     /// the function can be called directly. `unsafe` functions or calls where types
     /// get adjusted are ignored.
     ///
-    /// **Why is this bad?** Needlessly creating a closure adds code for no benefit
+    /// ### Why is this bad?
+    /// Needlessly creating a closure adds code for no benefit
     /// and gives the optimizer more work.
     ///
-    /// **Known problems:** If creating the closure inside the closure has a side-
+    /// ### Known problems
+    /// If creating the closure inside the closure has a side-
     /// effect then moving the closure creation out will change when that side-
     /// effect runs.
     /// See [#1439](https://github.com/rust-lang/rust-clippy/issues/1439) for more details.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust,ignore
     /// // Bad
     /// xs.map(|x| foo(x))
@@ -42,17 +45,20 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for closures which only invoke a method on the closure
+    /// ### What it does
+    /// Checks for closures which only invoke a method on the closure
     /// argument and can be replaced by referencing the method directly.
     ///
-    /// **Why is this bad?** It's unnecessary to create the closure.
+    /// ### Why is this bad?
+    /// It's unnecessary to create the closure.
     ///
-    /// **Known problems:** [#3071](https://github.com/rust-lang/rust-clippy/issues/3071),
+    /// ### Known problems
+    /// [#3071](https://github.com/rust-lang/rust-clippy/issues/3071),
     /// [#3942](https://github.com/rust-lang/rust-clippy/issues/3942),
     /// [#4002](https://github.com/rust-lang/rust-clippy/issues/4002)
     ///
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust,ignore
     /// Some('a').map(|s| s.to_uppercase());
     /// ```
diff --git a/clippy_lints/src/eval_order_dependence.rs b/clippy_lints/src/eval_order_dependence.rs
index 03a8b40df555f..f72a1e446d55c 100644
--- a/clippy_lints/src/eval_order_dependence.rs
+++ b/clippy_lints/src/eval_order_dependence.rs
@@ -9,17 +9,20 @@ use rustc_middle::ty;
 use rustc_session::{declare_lint_pass, declare_tool_lint};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for a read and a write to the same variable where
+    /// ### What it does
+    /// Checks for a read and a write to the same variable where
     /// whether the read occurs before or after the write depends on the evaluation
     /// order of sub-expressions.
     ///
-    /// **Why is this bad?** It is often confusing to read. In addition, the
+    /// ### Why is this bad?
+    /// It is often confusing to read. In addition, the
     /// sub-expression evaluation order for Rust is not well documented.
     ///
-    /// **Known problems:** Code which intentionally depends on the evaluation
+    /// ### Known problems
+    /// Code which intentionally depends on the evaluation
     /// order, or which is correct for any evaluation order.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// let mut x = 0;
     ///
@@ -43,16 +46,19 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for diverging calls that are not match arms or
+    /// ### What it does
+    /// Checks for diverging calls that are not match arms or
     /// statements.
     ///
-    /// **Why is this bad?** It is often confusing to read. In addition, the
+    /// ### Why is this bad?
+    /// It is often confusing to read. In addition, the
     /// sub-expression evaluation order for Rust is not well documented.
     ///
-    /// **Known problems:** Someone might want to use `some_bool || panic!()` as a
+    /// ### Known problems
+    /// Someone might want to use `some_bool || panic!()` as a
     /// shorthand.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust,no_run
     /// # fn b() -> bool { true }
     /// # fn c() -> bool { true }
diff --git a/clippy_lints/src/excessive_bools.rs b/clippy_lints/src/excessive_bools.rs
index 4e2dbf005d51c..476e6d23f1215 100644
--- a/clippy_lints/src/excessive_bools.rs
+++ b/clippy_lints/src/excessive_bools.rs
@@ -8,19 +8,19 @@ use rustc_span::{sym, Span};
 use std::convert::TryInto;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for excessive
+    /// ### What it does
+    /// Checks for excessive
     /// use of bools in structs.
     ///
-    /// **Why is this bad?** Excessive bools in a struct
+    /// ### Why is this bad?
+    /// Excessive bools in a struct
     /// is often a sign that it's used as a state machine,
     /// which is much better implemented as an enum.
     /// If it's not the case, excessive bools usually benefit
     /// from refactoring into two-variant enums for better
     /// readability and API.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// Bad:
     /// ```rust
     /// struct S {
@@ -44,19 +44,19 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for excessive use of
+    /// ### What it does
+    /// Checks for excessive use of
     /// bools in function definitions.
     ///
-    /// **Why is this bad?** Calls to such functions
+    /// ### Why is this bad?
+    /// Calls to such functions
     /// are confusing and error prone, because it's
     /// hard to remember argument order and you have
     /// no type system support to back you up. Using
     /// two-variant enums instead of bools often makes
     /// API easier to use.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// Bad:
     /// ```rust,ignore
     /// fn f(is_round: bool, is_hot: bool) { ... }
diff --git a/clippy_lints/src/exhaustive_items.rs b/clippy_lints/src/exhaustive_items.rs
index 60ad2e8ee1404..e00126046c022 100644
--- a/clippy_lints/src/exhaustive_items.rs
+++ b/clippy_lints/src/exhaustive_items.rs
@@ -8,16 +8,15 @@ use rustc_session::{declare_lint_pass, declare_tool_lint};
 use rustc_span::sym;
 
 declare_clippy_lint! {
-    /// **What it does:** Warns on any exported `enum`s that are not tagged `#[non_exhaustive]`
+    /// ### What it does
+    /// Warns on any exported `enum`s that are not tagged `#[non_exhaustive]`
     ///
-    /// **Why is this bad?** Exhaustive enums are typically fine, but a project which does
+    /// ### Why is this bad?
+    /// Exhaustive enums are typically fine, but a project which does
     /// not wish to make a stability commitment around exported enums may wish to
     /// disable them by default.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust
     /// enum Foo {
     ///     Bar,
@@ -38,16 +37,15 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Warns on any exported `structs`s that are not tagged `#[non_exhaustive]`
+    /// ### What it does
+    /// Warns on any exported `structs`s that are not tagged `#[non_exhaustive]`
     ///
-    /// **Why is this bad?** Exhaustive structs are typically fine, but a project which does
+    /// ### Why is this bad?
+    /// Exhaustive structs are typically fine, but a project which does
     /// not wish to make a stability commitment around exported structs may wish to
     /// disable them by default.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust
     /// struct Foo {
     ///     bar: u8,
diff --git a/clippy_lints/src/exit.rs b/clippy_lints/src/exit.rs
index 16246e548b613..9cd5b2d9f4439 100644
--- a/clippy_lints/src/exit.rs
+++ b/clippy_lints/src/exit.rs
@@ -6,15 +6,15 @@ use rustc_lint::{LateContext, LateLintPass};
 use rustc_session::{declare_lint_pass, declare_tool_lint};
 
 declare_clippy_lint! {
-    /// **What it does:** `exit()`  terminates the program and doesn't provide a
+    /// ### What it does
+    /// `exit()`  terminates the program and doesn't provide a
     /// stack trace.
     ///
-    /// **Why is this bad?** Ideally a program is terminated by finishing
+    /// ### Why is this bad?
+    /// Ideally a program is terminated by finishing
     /// the main function.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```ignore
     /// std::process::exit(0)
     /// ```
diff --git a/clippy_lints/src/explicit_write.rs b/clippy_lints/src/explicit_write.rs
index 66724294804a8..4f46ef906f409 100644
--- a/clippy_lints/src/explicit_write.rs
+++ b/clippy_lints/src/explicit_write.rs
@@ -9,14 +9,14 @@ use rustc_session::{declare_lint_pass, declare_tool_lint};
 use rustc_span::sym;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for usage of `write!()` / `writeln()!` which can be
+    /// ### What it does
+    /// Checks for usage of `write!()` / `writeln()!` which can be
     /// replaced with `(e)print!()` / `(e)println!()`
     ///
-    /// **Why is this bad?** Using `(e)println! is clearer and more concise
+    /// ### Why is this bad?
+    /// Using `(e)println! is clearer and more concise
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # use std::io::Write;
     /// # let bar = "furchtbar";
diff --git a/clippy_lints/src/fallible_impl_from.rs b/clippy_lints/src/fallible_impl_from.rs
index 2937fcb9ca0f3..7e4d1b3ef9f0d 100644
--- a/clippy_lints/src/fallible_impl_from.rs
+++ b/clippy_lints/src/fallible_impl_from.rs
@@ -10,13 +10,13 @@ use rustc_session::{declare_lint_pass, declare_tool_lint};
 use rustc_span::{sym, Span};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for impls of `From<..>` that contain `panic!()` or `unwrap()`
+    /// ### What it does
+    /// Checks for impls of `From<..>` that contain `panic!()` or `unwrap()`
     ///
-    /// **Why is this bad?** `TryFrom` should be used if there's a possibility of failure.
+    /// ### Why is this bad?
+    /// `TryFrom` should be used if there's a possibility of failure.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// struct Foo(i32);
     ///
diff --git a/clippy_lints/src/float_equality_without_abs.rs b/clippy_lints/src/float_equality_without_abs.rs
index 1e503cc795ccb..c33d80b8e8ef9 100644
--- a/clippy_lints/src/float_equality_without_abs.rs
+++ b/clippy_lints/src/float_equality_without_abs.rs
@@ -11,30 +11,32 @@ use rustc_session::{declare_lint_pass, declare_tool_lint};
 use rustc_span::source_map::Spanned;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for statements of the form `(a - b) < f32::EPSILON` or
-     /// `(a - b) < f64::EPSILON`. Notes the missing `.abs()`.
-     ///
-     /// **Why is this bad?** The code without `.abs()` is more likely to have a bug.
-     ///
-     /// **Known problems:** If the user can ensure that b is larger than a, the `.abs()` is
-     /// technically unneccessary. However, it will make the code more robust and doesn't have any
-     /// large performance implications. If the abs call was deliberately left out for performance
-     /// reasons, it is probably better to state this explicitly in the code, which then can be done
-     /// with an allow.
-     ///
-     /// **Example:**
-     ///
-     /// ```rust
-     /// pub fn is_roughly_equal(a: f32, b: f32) -> bool {
-     ///     (a - b) < f32::EPSILON
-     /// }
-     /// ```
-     /// Use instead:
-     /// ```rust
-     /// pub fn is_roughly_equal(a: f32, b: f32) -> bool {
-     ///     (a - b).abs() < f32::EPSILON
-     /// }
-     /// ```
+    /// ### What it does
+    /// Checks for statements of the form `(a - b) < f32::EPSILON` or
+    /// `(a - b) < f64::EPSILON`. Notes the missing `.abs()`.
+    ///
+    /// ### Why is this bad?
+    /// The code without `.abs()` is more likely to have a bug.
+    ///
+    /// ### Known problems
+    /// If the user can ensure that b is larger than a, the `.abs()` is
+    /// technically unneccessary. However, it will make the code more robust and doesn't have any
+    /// large performance implications. If the abs call was deliberately left out for performance
+    /// reasons, it is probably better to state this explicitly in the code, which then can be done
+    /// with an allow.
+    ///
+    /// ### Example
+    /// ```rust
+    /// pub fn is_roughly_equal(a: f32, b: f32) -> bool {
+    ///     (a - b) < f32::EPSILON
+    /// }
+    /// ```
+    /// Use instead:
+    /// ```rust
+    /// pub fn is_roughly_equal(a: f32, b: f32) -> bool {
+    ///     (a - b).abs() < f32::EPSILON
+    /// }
+    /// ```
     pub FLOAT_EQUALITY_WITHOUT_ABS,
     suspicious,
     "float equality check without `.abs()`"
diff --git a/clippy_lints/src/float_literal.rs b/clippy_lints/src/float_literal.rs
index 7968e7b764df3..a3d70f31f0021 100644
--- a/clippy_lints/src/float_literal.rs
+++ b/clippy_lints/src/float_literal.rs
@@ -10,15 +10,14 @@ use rustc_session::{declare_lint_pass, declare_tool_lint};
 use std::fmt;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for float literals with a precision greater
+    /// ### What it does
+    /// Checks for float literals with a precision greater
     /// than that supported by the underlying type.
     ///
-    /// **Why is this bad?** Rust will truncate the literal silently.
-    ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Why is this bad?
+    /// Rust will truncate the literal silently.
     ///
+    /// ### Example
     /// ```rust
     /// // Bad
     /// let v: f32 = 0.123_456_789_9;
@@ -34,16 +33,15 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for whole number float literals that
+    /// ### What it does
+    /// Checks for whole number float literals that
     /// cannot be represented as the underlying type without loss.
     ///
-    /// **Why is this bad?** Rust will silently lose precision during
+    /// ### Why is this bad?
+    /// Rust will silently lose precision during
     /// conversion to a float.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust
     /// // Bad
     /// let _: f32 = 16_777_217.0; // 16_777_216.0
diff --git a/clippy_lints/src/floating_point_arithmetic.rs b/clippy_lints/src/floating_point_arithmetic.rs
index e38384b01d414..b01c0cdd84624 100644
--- a/clippy_lints/src/floating_point_arithmetic.rs
+++ b/clippy_lints/src/floating_point_arithmetic.rs
@@ -18,16 +18,15 @@ use std::f64::consts as f64_consts;
 use sugg::Sugg;
 
 declare_clippy_lint! {
-    /// **What it does:** Looks for floating-point expressions that
+    /// ### What it does
+    /// Looks for floating-point expressions that
     /// can be expressed using built-in methods to improve accuracy
     /// at the cost of performance.
     ///
-    /// **Why is this bad?** Negatively impacts accuracy.
-    ///
-    /// **Known problems:** None
-    ///
-    /// **Example:**
+    /// ### Why is this bad?
+    /// Negatively impacts accuracy.
     ///
+    /// ### Example
     /// ```rust
     /// let a = 3f32;
     /// let _ = a.powf(1.0 / 3.0);
@@ -49,16 +48,15 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Looks for floating-point expressions that
+    /// ### What it does
+    /// Looks for floating-point expressions that
     /// can be expressed using built-in methods to improve both
     /// accuracy and performance.
     ///
-    /// **Why is this bad?** Negatively impacts accuracy and performance.
-    ///
-    /// **Known problems:** None
-    ///
-    /// **Example:**
+    /// ### Why is this bad?
+    /// Negatively impacts accuracy and performance.
     ///
+    /// ### Example
     /// ```rust
     /// use std::f32::consts::E;
     ///
diff --git a/clippy_lints/src/format.rs b/clippy_lints/src/format.rs
index ca3490d8edad9..863c606f5a92c 100644
--- a/clippy_lints/src/format.rs
+++ b/clippy_lints/src/format.rs
@@ -13,18 +13,18 @@ use rustc_span::symbol::kw;
 use rustc_span::{sym, Span};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for the use of `format!("string literal with no
+    /// ### What it does
+    /// Checks for the use of `format!("string literal with no
     /// argument")` and `format!("{}", foo)` where `foo` is a string.
     ///
-    /// **Why is this bad?** There is no point of doing that. `format!("foo")` can
+    /// ### Why is this bad?
+    /// There is no point of doing that. `format!("foo")` can
     /// be replaced by `"foo".to_owned()` if you really need a `String`. The even
     /// worse `&format!("foo")` is often encountered in the wild. `format!("{}",
     /// foo)` can be replaced by `foo.clone()` if `foo: String` or `foo.to_owned()`
     /// if `foo: &str`.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Examples:**
+    /// ### Examples
     /// ```rust
     ///
     /// // Bad
diff --git a/clippy_lints/src/formatting.rs b/clippy_lints/src/formatting.rs
index 8aefb8d46f6e8..b4cf1971d78dc 100644
--- a/clippy_lints/src/formatting.rs
+++ b/clippy_lints/src/formatting.rs
@@ -9,15 +9,15 @@ use rustc_session::{declare_lint_pass, declare_tool_lint};
 use rustc_span::source_map::Span;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for use of the non-existent `=*`, `=!` and `=-`
+    /// ### What it does
+    /// Checks for use of the non-existent `=*`, `=!` and `=-`
     /// operators.
     ///
-    /// **Why is this bad?** This is either a typo of `*=`, `!=` or `-=` or
+    /// ### Why is this bad?
+    /// This is either a typo of `*=`, `!=` or `-=` or
     /// confusing.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust,ignore
     /// a =- 42; // confusing, should it be `a -= 42` or `a = -42`?
     /// ```
@@ -27,15 +27,15 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks the formatting of a unary operator on the right hand side
+    /// ### What it does
+    /// Checks the formatting of a unary operator on the right hand side
     /// of a binary operator. It lints if there is no space between the binary and unary operators,
     /// but there is a space between the unary and its operand.
     ///
-    /// **Why is this bad?** This is either a typo in the binary operator or confusing.
-    ///
-    /// **Known problems:** None.
+    /// ### Why is this bad?
+    /// This is either a typo in the binary operator or confusing.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust,ignore
     /// if foo <- 30 { // this should be `foo < -30` but looks like a different operator
     /// }
@@ -49,15 +49,15 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for formatting of `else`. It lints if the `else`
+    /// ### What it does
+    /// Checks for formatting of `else`. It lints if the `else`
     /// is followed immediately by a newline or the `else` seems to be missing.
     ///
-    /// **Why is this bad?** This is probably some refactoring remnant, even if the
+    /// ### Why is this bad?
+    /// This is probably some refactoring remnant, even if the
     /// code is correct, it might look confusing.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust,ignore
     /// if foo {
     /// } { // looks like an `else` is missing here
@@ -85,14 +85,14 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for possible missing comma in an array. It lints if
+    /// ### What it does
+    /// Checks for possible missing comma in an array. It lints if
     /// an array element is a binary operator expression and it lies on two lines.
     ///
-    /// **Why is this bad?** This could lead to unexpected results.
-    ///
-    /// **Known problems:** None.
+    /// ### Why is this bad?
+    /// This could lead to unexpected results.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust,ignore
     /// let a = &[
     ///     -1, -2, -3 // <= no comma here
diff --git a/clippy_lints/src/from_over_into.rs b/clippy_lints/src/from_over_into.rs
index 48316c3a61df0..623546cd1dea9 100644
--- a/clippy_lints/src/from_over_into.rs
+++ b/clippy_lints/src/from_over_into.rs
@@ -8,14 +8,13 @@ use rustc_session::{declare_tool_lint, impl_lint_pass};
 use rustc_span::symbol::sym;
 
 declare_clippy_lint! {
-    /// **What it does:** Searches for implementations of the `Into<..>` trait and suggests to implement `From<..>` instead.
+    /// ### What it does
+    /// Searches for implementations of the `Into<..>` trait and suggests to implement `From<..>` instead.
     ///
-    /// **Why is this bad?** According the std docs implementing `From<..>` is preferred since it gives you `Into<..>` for free where the reverse isn't true.
-    ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Why is this bad?
+    /// According the std docs implementing `From<..>` is preferred since it gives you `Into<..>` for free where the reverse isn't true.
     ///
+    /// ### Example
     /// ```rust
     /// struct StringWrapper(String);
     ///
diff --git a/clippy_lints/src/from_str_radix_10.rs b/clippy_lints/src/from_str_radix_10.rs
index 3da5bc95b6db1..cc4bb85c50f7e 100644
--- a/clippy_lints/src/from_str_radix_10.rs
+++ b/clippy_lints/src/from_str_radix_10.rs
@@ -10,20 +10,22 @@ use rustc_session::{declare_lint_pass, declare_tool_lint};
 use rustc_span::symbol::sym;
 
 declare_clippy_lint! {
-    /// **What it does:**
+    /// ### What it does
+    ///
     /// Checks for function invocations of the form `primitive::from_str_radix(s, 10)`
     ///
-    /// **Why is this bad?**
+    /// ### Why is this bad?
+    ///
     /// This specific common use case can be rewritten as `s.parse::<primitive>()`
     /// (and in most cases, the turbofish can be removed), which reduces code length
     /// and complexity.
     ///
-    /// **Known problems:**
+    /// ### Known problems
+    ///
     /// This lint may suggest using (&<expression>).parse() instead of <expression>.parse() directly
     /// in some cases, which is correct but adds unnecessary complexity to the code.
     ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```ignore
     /// let input: &str = get_input();
     /// let num = u16::from_str_radix(input, 10)?;
diff --git a/clippy_lints/src/functions/mod.rs b/clippy_lints/src/functions/mod.rs
index 2beb9bc94bf06..ce23c0ce4a076 100644
--- a/clippy_lints/src/functions/mod.rs
+++ b/clippy_lints/src/functions/mod.rs
@@ -11,15 +11,15 @@ use rustc_session::{declare_tool_lint, impl_lint_pass};
 use rustc_span::Span;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for functions with too many parameters.
+    /// ### What it does
+    /// Checks for functions with too many parameters.
     ///
-    /// **Why is this bad?** Functions with lots of parameters are considered bad
+    /// ### Why is this bad?
+    /// Functions with lots of parameters are considered bad
     /// style and reduce readability (“what does the 5th parameter mean?”). Consider
     /// grouping some parameters into a new type.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # struct Color;
     /// fn foo(x: u32, y: u32, name: &str, c: Color, w: f32, h: f32, a: f32, b: f32) {
@@ -32,16 +32,16 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for functions with a large amount of lines.
+    /// ### What it does
+    /// Checks for functions with a large amount of lines.
     ///
-    /// **Why is this bad?** Functions with a lot of lines are harder to understand
+    /// ### Why is this bad?
+    /// Functions with a lot of lines are harder to understand
     /// due to having to look at a larger amount of code to understand what the
     /// function is doing. Consider splitting the body of the function into
     /// multiple functions.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// fn im_too_long() {
     ///     println!("");
@@ -55,15 +55,16 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for public functions that dereference raw pointer
+    /// ### What it does
+    /// Checks for public functions that dereference raw pointer
     /// arguments but are not marked `unsafe`.
     ///
-    /// **Why is this bad?** The function should probably be marked `unsafe`, since
+    /// ### Why is this bad?
+    /// The function should probably be marked `unsafe`, since
     /// for an arbitrary raw pointer, there is no way of telling for sure if it is
     /// valid.
     ///
-    /// **Known problems:**
-    ///
+    /// ### Known problems
     /// * It does not check functions recursively so if the pointer is passed to a
     /// private non-`unsafe` function which does the dereferencing, the lint won't
     /// trigger.
@@ -71,7 +72,7 @@ declare_clippy_lint! {
     /// got from an argument in some other way (`fn foo(bar: &[*const u8])` or
     /// `some_argument.get_raw_ptr()`).
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust,ignore
     /// // Bad
     /// pub fn foo(x: *const u8) {
@@ -89,17 +90,17 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for a [`#[must_use]`] attribute on
+    /// ### What it does
+    /// Checks for a [`#[must_use]`] attribute on
     /// unit-returning functions and methods.
     ///
     /// [`#[must_use]`]: https://doc.rust-lang.org/reference/attributes/diagnostics.html#the-must_use-attribute
     ///
-    /// **Why is this bad?** Unit values are useless. The attribute is likely
+    /// ### Why is this bad?
+    /// Unit values are useless. The attribute is likely
     /// a remnant of a refactoring that removed the return type.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Examples:**
+    /// ### Examples
     /// ```rust
     /// #[must_use]
     /// fn useless() { }
@@ -110,19 +111,19 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for a [`#[must_use]`] attribute without
+    /// ### What it does
+    /// Checks for a [`#[must_use]`] attribute without
     /// further information on functions and methods that return a type already
     /// marked as `#[must_use]`.
     ///
     /// [`#[must_use]`]: https://doc.rust-lang.org/reference/attributes/diagnostics.html#the-must_use-attribute
     ///
-    /// **Why is this bad?** The attribute isn't needed. Not using the result
+    /// ### Why is this bad?
+    /// The attribute isn't needed. Not using the result
     /// will already be reported. Alternatively, one can add some text to the
     /// attribute to improve the lint message.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Examples:**
+    /// ### Examples
     /// ```rust
     /// #[must_use]
     /// fn double_must_use() -> Result<(), ()> {
@@ -135,16 +136,19 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for public functions that have no
+    /// ### What it does
+    /// Checks for public functions that have no
     /// [`#[must_use]`] attribute, but return something not already marked
     /// must-use, have no mutable arg and mutate no statics.
     ///
     /// [`#[must_use]`]: https://doc.rust-lang.org/reference/attributes/diagnostics.html#the-must_use-attribute
     ///
-    /// **Why is this bad?** Not bad at all, this lint just shows places where
+    /// ### Why is this bad?
+    /// Not bad at all, this lint just shows places where
     /// you could add the attribute.
     ///
-    /// **Known problems:** The lint only checks the arguments for mutable
+    /// ### Known problems
+    /// The lint only checks the arguments for mutable
     /// types without looking if they are actually changed. On the other hand,
     /// it also ignores a broad range of potentially interesting side effects,
     /// because we cannot decide whether the programmer intends the function to
@@ -152,7 +156,7 @@ declare_clippy_lint! {
     /// positives. At least we don't lint if the result type is unit or already
     /// `#[must_use]`.
     ///
-    /// **Examples:**
+    /// ### Examples
     /// ```rust
     /// // this could be annotated with `#[must_use]`.
     /// fn id<T>(t: T) -> T { t }
@@ -163,20 +167,23 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for public functions that return a `Result`
+    /// ### What it does
+    /// Checks for public functions that return a `Result`
     /// with an `Err` type of `()`. It suggests using a custom type that
     /// implements `std::error::Error`.
     ///
-    /// **Why is this bad?** Unit does not implement `Error` and carries no
+    /// ### Why is this bad?
+    /// Unit does not implement `Error` and carries no
     /// further information about what went wrong.
     ///
-    /// **Known problems:** Of course, this lint assumes that `Result` is used
+    /// ### Known problems
+    /// Of course, this lint assumes that `Result` is used
     /// for a fallible operation (which is after all the intended use). However
     /// code may opt to (mis)use it as a basic two-variant-enum. In that case,
     /// the suggestion is misguided, and the code should use a custom enum
     /// instead.
     ///
-    /// **Examples:**
+    /// ### Examples
     /// ```rust
     /// pub fn read_u8() -> Result<u8, ()> { Err(()) }
     /// ```
diff --git a/clippy_lints/src/future_not_send.rs b/clippy_lints/src/future_not_send.rs
index 515b8887453b9..0be03969bcbe2 100644
--- a/clippy_lints/src/future_not_send.rs
+++ b/clippy_lints/src/future_not_send.rs
@@ -12,12 +12,14 @@ use rustc_trait_selection::traits::error_reporting::suggestions::InferCtxtExt;
 use rustc_trait_selection::traits::{self, FulfillmentError, TraitEngine};
 
 declare_clippy_lint! {
-    /// **What it does:** This lint requires Future implementations returned from
+    /// ### What it does
+    /// This lint requires Future implementations returned from
     /// functions and methods to implement the `Send` marker trait. It is mostly
     /// used by library authors (public and internal) that target an audience where
     /// multithreaded executors are likely to be used for running these Futures.
     ///
-    /// **Why is this bad?** A Future implementation captures some state that it
+    /// ### Why is this bad?
+    /// A Future implementation captures some state that it
     /// needs to eventually produce its final value. When targeting a multithreaded
     /// executor (which is the norm on non-embedded devices) this means that this
     /// state may need to be transported to other threads, in other words the
@@ -31,10 +33,7 @@ declare_clippy_lint! {
     /// modifying the library where the offending Future implementation is
     /// produced.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust
     /// async fn not_send(bytes: std::rc::Rc<[u8]>) {}
     /// ```
diff --git a/clippy_lints/src/get_last_with_len.rs b/clippy_lints/src/get_last_with_len.rs
index 8e45fdfecc447..ced35030de835 100644
--- a/clippy_lints/src/get_last_with_len.rs
+++ b/clippy_lints/src/get_last_with_len.rs
@@ -14,10 +14,12 @@ use rustc_span::source_map::Spanned;
 use rustc_span::sym;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for using `x.get(x.len() - 1)` instead of
+    /// ### What it does
+    /// Checks for using `x.get(x.len() - 1)` instead of
     /// `x.last()`.
     ///
-    /// **Why is this bad?** Using `x.last()` is easier to read and has the same
+    /// ### Why is this bad?
+    /// Using `x.last()` is easier to read and has the same
     /// result.
     ///
     /// Note that using `x[x.len() - 1]` is semantically different from
@@ -27,10 +29,7 @@ declare_clippy_lint! {
     /// There is another lint (get_unwrap) that covers the case of using
     /// `x.get(index).unwrap()` instead of `x[index]`.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust
     /// // Bad
     /// let x = vec![2, 3, 5];
diff --git a/clippy_lints/src/identity_op.rs b/clippy_lints/src/identity_op.rs
index 99c461930e4c1..5feb0ce8dece7 100644
--- a/clippy_lints/src/identity_op.rs
+++ b/clippy_lints/src/identity_op.rs
@@ -11,14 +11,14 @@ use clippy_utils::diagnostics::span_lint;
 use clippy_utils::{clip, unsext};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for identity operations, e.g., `x + 0`.
+    /// ### What it does
+    /// Checks for identity operations, e.g., `x + 0`.
     ///
-    /// **Why is this bad?** This code can be removed without changing the
+    /// ### Why is this bad?
+    /// This code can be removed without changing the
     /// meaning. So it just obscures what's going on. Delete it mercilessly.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # let x = 1;
     /// x / 1 + 0 * 1 - 0 | 0;
diff --git a/clippy_lints/src/if_let_mutex.rs b/clippy_lints/src/if_let_mutex.rs
index 5403d76ea30c8..d3ddeda9fd1b9 100644
--- a/clippy_lints/src/if_let_mutex.rs
+++ b/clippy_lints/src/if_let_mutex.rs
@@ -9,16 +9,15 @@ use rustc_middle::hir::map::Map;
 use rustc_session::{declare_lint_pass, declare_tool_lint};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for `Mutex::lock` calls in `if let` expression
+    /// ### What it does
+    /// Checks for `Mutex::lock` calls in `if let` expression
     /// with lock calls in any of the else blocks.
     ///
-    /// **Why is this bad?** The Mutex lock remains held for the whole
+    /// ### Why is this bad?
+    /// The Mutex lock remains held for the whole
     /// `if let ... else` block and deadlocks.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust,ignore
     /// if let Ok(thing) = mutex.lock() {
     ///     do_thing();
diff --git a/clippy_lints/src/if_let_some_result.rs b/clippy_lints/src/if_let_some_result.rs
index 611da3744eeee..587307811a113 100644
--- a/clippy_lints/src/if_let_some_result.rs
+++ b/clippy_lints/src/if_let_some_result.rs
@@ -10,14 +10,14 @@ use rustc_session::{declare_lint_pass, declare_tool_lint};
 use rustc_span::sym;
 
 declare_clippy_lint! {
-    /// **What it does:*** Checks for unnecessary `ok()` in if let.
+    /// ### What it does
+    ///* Checks for unnecessary `ok()` in if let.
     ///
-    /// **Why is this bad?** Calling `ok()` in if let is unnecessary, instead match
+    /// ### Why is this bad?
+    /// Calling `ok()` in if let is unnecessary, instead match
     /// on `Ok(pat)`
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```ignore
     /// for i in iter {
     ///     if let Some(value) = i.parse().ok() {
diff --git a/clippy_lints/src/if_not_else.rs b/clippy_lints/src/if_not_else.rs
index c56f67df0618f..28db7233d70e8 100644
--- a/clippy_lints/src/if_not_else.rs
+++ b/clippy_lints/src/if_not_else.rs
@@ -8,14 +8,14 @@ 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 `!` or `!=` in an if condition with an
+    /// ### What it does
+    /// Checks for usage of `!` or `!=` in an if condition with an
     /// else branch.
     ///
-    /// **Why is this bad?** Negations reduce the readability of statements.
+    /// ### Why is this bad?
+    /// Negations reduce the readability of statements.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # let v: Vec<usize> = vec![];
     /// # fn a() {}
diff --git a/clippy_lints/src/if_then_some_else_none.rs b/clippy_lints/src/if_then_some_else_none.rs
index eadcd0867a880..17b9a2f888e0d 100644
--- a/clippy_lints/src/if_then_some_else_none.rs
+++ b/clippy_lints/src/if_then_some_else_none.rs
@@ -10,14 +10,13 @@ use rustc_semver::RustcVersion;
 use rustc_session::{declare_tool_lint, impl_lint_pass};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for if-else that could be written to `bool::then`.
+    /// ### What it does
+    /// Checks for if-else that could be written to `bool::then`.
     ///
-    /// **Why is this bad?** Looks a little redundant. Using `bool::then` helps it have less lines of code.
-    ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Why is this bad?
+    /// Looks a little redundant. Using `bool::then` helps it have less lines of code.
     ///
+    /// ### Example
     /// ```rust
     /// # let v = vec![0];
     /// let a = if v.is_empty() {
diff --git a/clippy_lints/src/implicit_hasher.rs b/clippy_lints/src/implicit_hasher.rs
index 879d6a75bbedd..aae44f64e6695 100644
--- a/clippy_lints/src/implicit_hasher.rs
+++ b/clippy_lints/src/implicit_hasher.rs
@@ -22,18 +22,21 @@ use clippy_utils::source::{snippet, snippet_opt};
 use clippy_utils::ty::is_type_diagnostic_item;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for public `impl` or `fn` missing generalization
+    /// ### What it does
+    /// Checks for public `impl` or `fn` missing generalization
     /// over different hashers and implicitly defaulting to the default hashing
     /// algorithm (`SipHash`).
     ///
-    /// **Why is this bad?** `HashMap` or `HashSet` with custom hashers cannot be
+    /// ### Why is this bad?
+    /// `HashMap` or `HashSet` with custom hashers cannot be
     /// used with them.
     ///
-    /// **Known problems:** Suggestions for replacing constructors can contain
+    /// ### Known problems
+    /// Suggestions for replacing constructors can contain
     /// false-positives. Also applying suggestions can require modification of other
     /// pieces of code, possibly including external crates.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # use std::collections::HashMap;
     /// # use std::hash::{Hash, BuildHasher};
diff --git a/clippy_lints/src/implicit_return.rs b/clippy_lints/src/implicit_return.rs
index f2f830ca5c09e..fa7b5302cb131 100644
--- a/clippy_lints/src/implicit_return.rs
+++ b/clippy_lints/src/implicit_return.rs
@@ -13,17 +13,17 @@ use rustc_session::{declare_lint_pass, declare_tool_lint};
 use rustc_span::{Span, SyntaxContext};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for missing return statements at the end of a block.
+    /// ### What it does
+    /// Checks for missing return statements at the end of a block.
     ///
-    /// **Why is this bad?** Actually omitting the return keyword is idiomatic Rust code. Programmers
+    /// ### Why is this bad?
+    /// Actually omitting the return keyword is idiomatic Rust code. Programmers
     /// coming from other languages might prefer the expressiveness of `return`. It's possible to miss
     /// the last returning statement because the only difference is a missing `;`. Especially in bigger
     /// code with multiple return paths having a `return` keyword makes it easier to find the
     /// corresponding statements.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// fn foo(x: usize) -> usize {
     ///     x
diff --git a/clippy_lints/src/implicit_saturating_sub.rs b/clippy_lints/src/implicit_saturating_sub.rs
index 4069a685ea0a4..0a7d31dce2fd5 100644
--- a/clippy_lints/src/implicit_saturating_sub.rs
+++ b/clippy_lints/src/implicit_saturating_sub.rs
@@ -8,14 +8,13 @@ use rustc_lint::{LateContext, LateLintPass};
 use rustc_session::{declare_lint_pass, declare_tool_lint};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for implicit saturating subtraction.
+    /// ### What it does
+    /// Checks for implicit saturating subtraction.
     ///
-    /// **Why is this bad?** Simplicity and readability. Instead we can easily use an builtin function.
-    ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Why is this bad?
+    /// Simplicity and readability. Instead we can easily use an builtin function.
     ///
+    /// ### Example
     /// ```rust
     /// let end: u32 = 10;
     /// let start: u32 = 5;
diff --git a/clippy_lints/src/inconsistent_struct_constructor.rs b/clippy_lints/src/inconsistent_struct_constructor.rs
index 3b635071f28aa..1f8240a1f636a 100644
--- a/clippy_lints/src/inconsistent_struct_constructor.rs
+++ b/clippy_lints/src/inconsistent_struct_constructor.rs
@@ -10,11 +10,13 @@ use rustc_session::{declare_lint_pass, declare_tool_lint};
 use rustc_span::symbol::Symbol;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for struct constructors where all fields are shorthand and
+    /// ### What it does
+    /// Checks for struct constructors where all fields are shorthand and
     /// the order of the field init shorthand in the constructor is inconsistent
     /// with the order in the struct definition.
     ///
-    /// **Why is this bad?** Since the order of fields in a constructor doesn't affect the
+    /// ### Why is this bad?
+    /// Since the order of fields in a constructor doesn't affect the
     /// resulted instance as the below example indicates,
     ///
     /// ```rust
@@ -32,10 +34,7 @@ declare_clippy_lint! {
     ///
     /// inconsistent order can be confusing and decreases readability and consistency.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust
     /// struct Foo {
     ///     x: i32,
diff --git a/clippy_lints/src/indexing_slicing.rs b/clippy_lints/src/indexing_slicing.rs
index bfa284f333a1a..8c1f107330955 100644
--- a/clippy_lints/src/indexing_slicing.rs
+++ b/clippy_lints/src/indexing_slicing.rs
@@ -10,14 +10,17 @@ use rustc_middle::ty;
 use rustc_session::{declare_lint_pass, declare_tool_lint};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for out of bounds array indexing with a constant
+    /// ### What it does
+    /// Checks for out of bounds array indexing with a constant
     /// index.
     ///
-    /// **Why is this bad?** This will always panic at runtime.
+    /// ### Why is this bad?
+    /// This will always panic at runtime.
     ///
-    /// **Known problems:** Hopefully none.
+    /// ### Known problems
+    /// Hopefully none.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```no_run
     /// # #![allow(const_err)]
     /// let x = [1, 2, 3, 4];
@@ -36,16 +39,19 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for usage of indexing or slicing. Arrays are special cases, this lint
+    /// ### What it does
+    /// Checks for usage of indexing or slicing. Arrays are special cases, this lint
     /// does report on arrays if we can tell that slicing operations are in bounds and does not
     /// lint on constant `usize` indexing on arrays because that is handled by rustc's `const_err` lint.
     ///
-    /// **Why is this bad?** Indexing and slicing can panic at runtime and there are
+    /// ### Why is this bad?
+    /// Indexing and slicing can panic at runtime and there are
     /// safe alternatives.
     ///
-    /// **Known problems:** Hopefully none.
+    /// ### Known problems
+    /// Hopefully none.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust,no_run
     /// // Vector
     /// let x = vec![0; 5];
diff --git a/clippy_lints/src/infinite_iter.rs b/clippy_lints/src/infinite_iter.rs
index 295a4e1fccb0a..2411a3175b919 100644
--- a/clippy_lints/src/infinite_iter.rs
+++ b/clippy_lints/src/infinite_iter.rs
@@ -7,14 +7,14 @@ use rustc_session::{declare_lint_pass, declare_tool_lint};
 use rustc_span::symbol::{sym, Symbol};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for iteration that is guaranteed to be infinite.
+    /// ### What it does
+    /// Checks for iteration that is guaranteed to be infinite.
     ///
-    /// **Why is this bad?** While there may be places where this is acceptable
+    /// ### Why is this bad?
+    /// While there may be places where this is acceptable
     /// (e.g., in event streams), in most cases this is simply an error.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```no_run
     /// use std::iter;
     ///
@@ -26,15 +26,18 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for iteration that may be infinite.
+    /// ### What it does
+    /// Checks for iteration that may be infinite.
     ///
-    /// **Why is this bad?** While there may be places where this is acceptable
+    /// ### Why is this bad?
+    /// While there may be places where this is acceptable
     /// (e.g., in event streams), in most cases this is simply an error.
     ///
-    /// **Known problems:** The code may have a condition to stop iteration, but
+    /// ### Known problems
+    /// The code may have a condition to stop iteration, but
     /// this lint is not clever enough to analyze it.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// let infinite_iter = 0..;
     /// [0..].iter().zip(infinite_iter.take_while(|x| *x > 5));
diff --git a/clippy_lints/src/inherent_impl.rs b/clippy_lints/src/inherent_impl.rs
index 9641784eb9a27..d87055c842c8c 100644
--- a/clippy_lints/src/inherent_impl.rs
+++ b/clippy_lints/src/inherent_impl.rs
@@ -10,13 +10,13 @@ use rustc_span::Span;
 use std::collections::hash_map::Entry;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for multiple inherent implementations of a struct
+    /// ### What it does
+    /// Checks for multiple inherent implementations of a struct
     ///
-    /// **Why is this bad?** Splitting the implementation of a type makes the code harder to navigate.
+    /// ### Why is this bad?
+    /// Splitting the implementation of a type makes the code harder to navigate.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// struct X;
     /// impl X {
diff --git a/clippy_lints/src/inherent_to_string.rs b/clippy_lints/src/inherent_to_string.rs
index b023e13e846c7..b62fad4bd3958 100644
--- a/clippy_lints/src/inherent_to_string.rs
+++ b/clippy_lints/src/inherent_to_string.rs
@@ -8,14 +8,16 @@ use rustc_session::{declare_lint_pass, declare_tool_lint};
 use rustc_span::sym;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for the definition of inherent methods with a signature of `to_string(&self) -> String`.
+    /// ### What it does
+    /// Checks for the definition of inherent methods with a signature of `to_string(&self) -> String`.
     ///
-    /// **Why is this bad?** This method is also implicitly defined if a type implements the `Display` trait. As the functionality of `Display` is much more versatile, it should be preferred.
+    /// ### Why is this bad?
+    /// This method is also implicitly defined if a type implements the `Display` trait. As the functionality of `Display` is much more versatile, it should be preferred.
     ///
-    /// **Known problems:** None
-    ///
-    /// ** Example:**
+    /// ### Known problems
+    /// None
     ///
+    /// ### Example
     /// ```rust
     /// // Bad
     /// pub struct A;
@@ -45,14 +47,16 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for the definition of inherent methods with a signature of `to_string(&self) -> String` and if the type implementing this method also implements the `Display` trait.
-    ///
-    /// **Why is this bad?** This method is also implicitly defined if a type implements the `Display` trait. The less versatile inherent method will then shadow the implementation introduced by `Display`.
+    /// ### What it does
+    /// Checks for the definition of inherent methods with a signature of `to_string(&self) -> String` and if the type implementing this method also implements the `Display` trait.
     ///
-    /// **Known problems:** None
+    /// ### Why is this bad?
+    /// This method is also implicitly defined if a type implements the `Display` trait. The less versatile inherent method will then shadow the implementation introduced by `Display`.
     ///
-    /// ** Example:**
+    /// ### Known problems
+    /// None
     ///
+    /// ### Example
     /// ```rust
     /// // Bad
     /// use std::fmt;
diff --git a/clippy_lints/src/inline_fn_without_body.rs b/clippy_lints/src/inline_fn_without_body.rs
index 20f00bd51ba86..3e3df903f17cf 100644
--- a/clippy_lints/src/inline_fn_without_body.rs
+++ b/clippy_lints/src/inline_fn_without_body.rs
@@ -10,14 +10,14 @@ use rustc_session::{declare_lint_pass, declare_tool_lint};
 use rustc_span::{sym, Symbol};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for `#[inline]` on trait methods without bodies
+    /// ### What it does
+    /// Checks for `#[inline]` on trait methods without bodies
     ///
-    /// **Why is this bad?** Only implementations of trait methods may be inlined.
+    /// ### Why is this bad?
+    /// Only implementations of trait methods may be inlined.
     /// The inline attribute is ignored for trait methods without bodies.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// trait Animal {
     ///     #[inline]
diff --git a/clippy_lints/src/int_plus_one.rs b/clippy_lints/src/int_plus_one.rs
index c4a1222b51fbe..49b69dd072a21 100644
--- a/clippy_lints/src/int_plus_one.rs
+++ b/clippy_lints/src/int_plus_one.rs
@@ -8,13 +8,13 @@ use rustc_lint::{EarlyContext, EarlyLintPass};
 use rustc_session::{declare_lint_pass, declare_tool_lint};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for usage of `x >= y + 1` or `x - 1 >= y` (and `<=`) in a block
+    /// ### What it does
+    /// Checks for usage of `x >= y + 1` or `x - 1 >= y` (and `<=`) in a block
     ///
-    /// **Why is this bad?** Readability -- better to use `> y` instead of `>= y + 1`.
+    /// ### Why is this bad?
+    /// Readability -- better to use `> y` instead of `>= y + 1`.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # let x = 1;
     /// # let y = 1;
diff --git a/clippy_lints/src/integer_division.rs b/clippy_lints/src/integer_division.rs
index e5482f675e78b..a0e6f12b8122e 100644
--- a/clippy_lints/src/integer_division.rs
+++ b/clippy_lints/src/integer_division.rs
@@ -5,15 +5,15 @@ use rustc_lint::{LateContext, LateLintPass};
 use rustc_session::{declare_lint_pass, declare_tool_lint};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for division of integers
+    /// ### What it does
+    /// Checks for division of integers
     ///
-    /// **Why is this bad?** When outside of some very specific algorithms,
+    /// ### Why is this bad?
+    /// When outside of some very specific algorithms,
     /// integer division is very often a mistake because it discards the
     /// remainder.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// // Bad
     /// let x = 3 / 2;
diff --git a/clippy_lints/src/invalid_upcast_comparisons.rs b/clippy_lints/src/invalid_upcast_comparisons.rs
index 37011f5578dc8..3b28b1212048a 100644
--- a/clippy_lints/src/invalid_upcast_comparisons.rs
+++ b/clippy_lints/src/invalid_upcast_comparisons.rs
@@ -14,18 +14,20 @@ use clippy_utils::source::snippet;
 use clippy_utils::{comparisons, sext};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for comparisons where the relation is always either
+    /// ### What it does
+    /// Checks for comparisons where the relation is always either
     /// true or false, but where one side has been upcast so that the comparison is
     /// necessary. Only integer types are checked.
     ///
-    /// **Why is this bad?** An expression like `let x : u8 = ...; (x as u32) > 300`
+    /// ### Why is this bad?
+    /// An expression like `let x : u8 = ...; (x as u32) > 300`
     /// will mistakenly imply that it is possible for `x` to be outside the range of
     /// `u8`.
     ///
-    /// **Known problems:**
+    /// ### Known problems
     /// https://github.com/rust-lang/rust-clippy/issues/886
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// let x: u8 = 1;
     /// (x as u32) > 300;
diff --git a/clippy_lints/src/items_after_statements.rs b/clippy_lints/src/items_after_statements.rs
index c69571f32a244..429c6ed7d2d77 100644
--- a/clippy_lints/src/items_after_statements.rs
+++ b/clippy_lints/src/items_after_statements.rs
@@ -7,15 +7,15 @@ use rustc_middle::lint::in_external_macro;
 use rustc_session::{declare_lint_pass, declare_tool_lint};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for items declared after some statement in a block.
+    /// ### What it does
+    /// Checks for items declared after some statement in a block.
     ///
-    /// **Why is this bad?** Items live for the entire scope they are declared
+    /// ### Why is this bad?
+    /// Items live for the entire scope they are declared
     /// in. But statements are processed in order. This might cause confusion as
     /// it's hard to figure out which item is meant in a statement.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// // Bad
     /// fn foo() {
diff --git a/clippy_lints/src/large_const_arrays.rs b/clippy_lints/src/large_const_arrays.rs
index 48dc5fefe9978..5d4e06c2af082 100644
--- a/clippy_lints/src/large_const_arrays.rs
+++ b/clippy_lints/src/large_const_arrays.rs
@@ -11,15 +11,15 @@ use rustc_span::{BytePos, Pos, Span};
 use rustc_typeck::hir_ty_to_ty;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for large `const` arrays that should
+    /// ### What it does
+    /// Checks for large `const` arrays that should
     /// be defined as `static` instead.
     ///
-    /// **Why is this bad?** Performance: const variables are inlined upon use.
+    /// ### Why is this bad?
+    /// Performance: const variables are inlined upon use.
     /// Static items result in only one instance and has a fixed location in memory.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust,ignore
     /// // Bad
     /// pub const a = [0u32; 1_000_000];
diff --git a/clippy_lints/src/large_enum_variant.rs b/clippy_lints/src/large_enum_variant.rs
index f166748d86b81..cde2336b690fd 100644
--- a/clippy_lints/src/large_enum_variant.rs
+++ b/clippy_lints/src/large_enum_variant.rs
@@ -10,20 +10,22 @@ use rustc_session::{declare_tool_lint, impl_lint_pass};
 use rustc_target::abi::LayoutOf;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for large size differences between variants on
+    /// ### What it does
+    /// Checks for large size differences between variants on
     /// `enum`s.
     ///
-    /// **Why is this bad?** Enum size is bounded by the largest variant. Having a
+    /// ### Why is this bad?
+    /// Enum size is bounded by the largest variant. Having a
     /// large variant can penalize the memory layout of that enum.
     ///
-    /// **Known problems:** This lint obviously cannot take the distribution of
+    /// ### Known problems
+    /// This lint obviously cannot take the distribution of
     /// variants in your running program into account. It is possible that the
     /// smaller variants make up less than 1% of all instances, in which case
     /// the overhead is negligible and the boxing is counter-productive. Always
     /// measure the change this lint suggests.
     ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust
     /// // Bad
     /// enum Test {
diff --git a/clippy_lints/src/large_stack_arrays.rs b/clippy_lints/src/large_stack_arrays.rs
index c46b98022c6ca..7088630bfdbb4 100644
--- a/clippy_lints/src/large_stack_arrays.rs
+++ b/clippy_lints/src/large_stack_arrays.rs
@@ -10,13 +10,13 @@ use rustc_session::{declare_tool_lint, impl_lint_pass};
 use crate::rustc_target::abi::LayoutOf;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for local arrays that may be too large.
+    /// ### What it does
+    /// Checks for local arrays that may be too large.
     ///
-    /// **Why is this bad?** Large local arrays may cause stack overflow.
+    /// ### Why is this bad?
+    /// Large local arrays may cause stack overflow.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust,ignore
     /// let a = [0u32; 1_000_000];
     /// ```
diff --git a/clippy_lints/src/len_zero.rs b/clippy_lints/src/len_zero.rs
index 892b3af0b3203..b66d7a9f7294f 100644
--- a/clippy_lints/src/len_zero.rs
+++ b/clippy_lints/src/len_zero.rs
@@ -18,17 +18,17 @@ use rustc_span::{
 };
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for getting the length of something via `.len()`
+    /// ### What it does
+    /// Checks for getting the length of something via `.len()`
     /// just to compare to zero, and suggests using `.is_empty()` where applicable.
     ///
-    /// **Why is this bad?** Some structures can answer `.is_empty()` much faster
+    /// ### Why is this bad?
+    /// Some structures can answer `.is_empty()` much faster
     /// than calculating their length. So it is good to get into the habit of using
     /// `.is_empty()`, and having it is cheap.
     /// Besides, it makes the intent clearer than a manual comparison in some contexts.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```ignore
     /// if x.len() == 0 {
     ///     ..
@@ -52,18 +52,18 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for items that implement `.len()` but not
+    /// ### What it does
+    /// Checks for items that implement `.len()` but not
     /// `.is_empty()`.
     ///
-    /// **Why is this bad?** It is good custom to have both methods, because for
+    /// ### Why is this bad?
+    /// It is good custom to have both methods, because for
     /// some data structures, asking about the length will be a costly operation,
     /// whereas `.is_empty()` can usually answer in constant time. Also it used to
     /// lead to false positives on the [`len_zero`](#len_zero) lint – currently that
     /// lint will ignore such entities.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```ignore
     /// impl X {
     ///     pub fn len(&self) -> usize {
@@ -77,17 +77,17 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for comparing to an empty slice such as `""` or `[]`,
+    /// ### What it does
+    /// Checks for comparing to an empty slice such as `""` or `[]`,
     /// and suggests using `.is_empty()` where applicable.
     ///
-    /// **Why is this bad?** Some structures can answer `.is_empty()` much faster
+    /// ### Why is this bad?
+    /// Some structures can answer `.is_empty()` much faster
     /// than checking for equality. So it is good to get into the habit of using
     /// `.is_empty()`, and having it is cheap.
     /// Besides, it makes the intent clearer than a manual comparison in some contexts.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     ///
     /// ```ignore
     /// if s == "" {
diff --git a/clippy_lints/src/let_if_seq.rs b/clippy_lints/src/let_if_seq.rs
index 67eae4d87bbdb..13f0d43cf8dd1 100644
--- a/clippy_lints/src/let_if_seq.rs
+++ b/clippy_lints/src/let_if_seq.rs
@@ -9,14 +9,14 @@ use rustc_lint::{LateContext, LateLintPass};
 use rustc_session::{declare_lint_pass, declare_tool_lint};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for variable declarations immediately followed by a
+    /// ### What it does
+    /// Checks for variable declarations immediately followed by a
     /// conditional affectation.
     ///
-    /// **Why is this bad?** This is not idiomatic Rust.
+    /// ### Why is this bad?
+    /// This is not idiomatic Rust.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust,ignore
     /// let foo;
     ///
diff --git a/clippy_lints/src/let_underscore.rs b/clippy_lints/src/let_underscore.rs
index e627b1385bc7d..8992d25932cad 100644
--- a/clippy_lints/src/let_underscore.rs
+++ b/clippy_lints/src/let_underscore.rs
@@ -9,15 +9,15 @@ use rustc_middle::ty::subst::GenericArgKind;
 use rustc_session::{declare_lint_pass, declare_tool_lint};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for `let _ = <expr>`
+    /// ### What it does
+    /// Checks for `let _ = <expr>`
     /// where expr is #[must_use]
     ///
-    /// **Why is this bad?** It's better to explicitly
+    /// ### Why is this bad?
+    /// It's better to explicitly
     /// handle the value of a #[must_use] expr
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// fn f() -> Result<u32, u32> {
     ///     Ok(0)
@@ -33,17 +33,17 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for `let _ = sync_lock`
+    /// ### What it does
+    /// Checks for `let _ = sync_lock`
     ///
-    /// **Why is this bad?** This statement immediately drops the lock instead of
+    /// ### Why is this bad?
+    /// This statement immediately drops the lock instead of
     /// extending its lifetime to the end of the scope, which is often not intended.
     /// To extend lock lifetime to the end of the scope, use an underscore-prefixed
     /// name instead (i.e. _lock). If you want to explicitly drop the lock,
     /// `std::mem::drop` conveys your intention better and is less error-prone.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     ///
     /// Bad:
     /// ```rust,ignore
@@ -60,19 +60,19 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for `let _ = <expr>`
+    /// ### What it does
+    /// Checks for `let _ = <expr>`
     /// where expr has a type that implements `Drop`
     ///
-    /// **Why is this bad?** This statement immediately drops the initializer
+    /// ### Why is this bad?
+    /// This statement immediately drops the initializer
     /// expression instead of extending its lifetime to the end of the scope, which
     /// is often not intended. To extend the expression's lifetime to the end of the
     /// scope, use an underscore-prefixed name instead (i.e. _var). If you want to
     /// explicitly drop the expression, `std::mem::drop` conveys your intention
     /// better and is less error-prone.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     ///
     /// Bad:
     /// ```rust,ignore
diff --git a/clippy_lints/src/lib.rs b/clippy_lints/src/lib.rs
index aa763b5c5e666..3cffb507f703a 100644
--- a/clippy_lints/src/lib.rs
+++ b/clippy_lints/src/lib.rs
@@ -73,14 +73,13 @@ use rustc_session::Session;
 /// use clippy_lints::declare_clippy_lint;
 ///
 /// declare_clippy_lint! {
-///     /// **What it does:** Checks for ... (describe what the lint matches).
+///     /// ### What it does
+///     /// Checks for ... (describe what the lint matches).
 ///     ///
-///     /// **Why is this bad?** Supply the reason for linting the code.
-///     ///
-///     /// **Known problems:** None. (Or describe where it could go wrong.)
-///     ///
-///     /// **Example:**
+///     /// ### Why is this bad?
+///     /// Supply the reason for linting the code.
 ///     ///
+///     /// ### Example
 ///     /// ```rust
 ///     /// // Bad
 ///     /// Insert a short example of code that triggers the lint
diff --git a/clippy_lints/src/lifetimes.rs b/clippy_lints/src/lifetimes.rs
index 5ae68ba5b2fe7..e5e6f8d25cc11 100644
--- a/clippy_lints/src/lifetimes.rs
+++ b/clippy_lints/src/lifetimes.rs
@@ -18,20 +18,22 @@ use rustc_span::source_map::Span;
 use rustc_span::symbol::{kw, Symbol};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for lifetime annotations which can be removed by
+    /// ### What it does
+    /// Checks for lifetime annotations which can be removed by
     /// relying on lifetime elision.
     ///
-    /// **Why is this bad?** The additional lifetimes make the code look more
+    /// ### Why is this bad?
+    /// The additional lifetimes make the code look more
     /// complicated, while there is nothing out of the ordinary going on. Removing
     /// them leads to more readable code.
     ///
-    /// **Known problems:**
+    /// ### Known problems
     /// - We bail out if the function has a `where` clause where lifetimes
     /// are mentioned due to potenial false positives.
     /// - Lifetime bounds such as `impl Foo + 'a` and `T: 'a` must be elided with the
     /// placeholder notation `'_` because the fully elided notation leaves the type bound to `'static`.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// // Bad: unnecessary lifetime annotations
     /// fn in_and_out<'a>(x: &'a u8, y: u8) -> &'a u8 {
@@ -50,16 +52,16 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for lifetimes in generics that are never used
+    /// ### What it does
+    /// Checks for lifetimes in generics that are never used
     /// anywhere else.
     ///
-    /// **Why is this bad?** The additional lifetimes make the code look more
+    /// ### Why is this bad?
+    /// The additional lifetimes make the code look more
     /// complicated, while there is nothing out of the ordinary going on. Removing
     /// them leads to more readable code.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// // Bad: unnecessary lifetimes
     /// fn unused_lifetime<'a>(x: u8) {
diff --git a/clippy_lints/src/literal_representation.rs b/clippy_lints/src/literal_representation.rs
index e0c5578bd603f..699ddce0cff90 100644
--- a/clippy_lints/src/literal_representation.rs
+++ b/clippy_lints/src/literal_representation.rs
@@ -16,15 +16,14 @@ use rustc_session::{declare_tool_lint, impl_lint_pass};
 use std::iter;
 
 declare_clippy_lint! {
-    /// **What it does:** Warns if a long integral or floating-point constant does
+    /// ### What it does
+    /// Warns if a long integral or floating-point constant does
     /// not contain underscores.
     ///
-    /// **Why is this bad?** Reading long numbers is difficult without separators.
-    ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Why is this bad?
+    /// Reading long numbers is difficult without separators.
     ///
+    /// ### Example
     /// ```rust
     /// // Bad
     /// let x: u64 = 61864918973511;
@@ -38,17 +37,18 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Warns for mistyped suffix in literals
+    /// ### What it does
+    /// Warns for mistyped suffix in literals
     ///
-    /// **Why is this bad?** This is most probably a typo
+    /// ### Why is this bad?
+    /// This is most probably a typo
     ///
-    /// **Known problems:**
+    /// ### Known problems
     /// - Recommends a signed suffix, even though the number might be too big and an unsigned
     ///   suffix is required
     /// - Does not match on `_127` since that is a valid grouping for decimal and octal numbers
     ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust
     /// // Probably mistyped
     /// 2_32;
@@ -62,16 +62,15 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Warns if an integral or floating-point constant is
+    /// ### What it does
+    /// Warns if an integral or floating-point constant is
     /// grouped inconsistently with underscores.
     ///
-    /// **Why is this bad?** Readers may incorrectly interpret inconsistently
+    /// ### Why is this bad?
+    /// Readers may incorrectly interpret inconsistently
     /// grouped digits.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust
     /// // Bad
     /// let x: u64 = 618_64_9189_73_511;
@@ -85,15 +84,14 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Warns if hexadecimal or binary literals are not grouped
+    /// ### What it does
+    /// Warns if hexadecimal or binary literals are not grouped
     /// by nibble or byte.
     ///
-    /// **Why is this bad?** Negatively impacts readability.
-    ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Why is this bad?
+    /// Negatively impacts readability.
     ///
+    /// ### Example
     /// ```rust
     /// let x: u32 = 0xFFF_FFF;
     /// let y: u8 = 0b01_011_101;
@@ -104,16 +102,15 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Warns if the digits of an integral or floating-point
+    /// ### What it does
+    /// Warns if the digits of an integral or floating-point
     /// constant are grouped into groups that
     /// are too large.
     ///
-    /// **Why is this bad?** Negatively impacts readability.
-    ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Why is this bad?
+    /// Negatively impacts readability.
     ///
+    /// ### Example
     /// ```rust
     /// let x: u64 = 6186491_8973511;
     /// ```
@@ -123,15 +120,14 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Warns if there is a better representation for a numeric literal.
+    /// ### What it does
+    /// Warns if there is a better representation for a numeric literal.
     ///
-    /// **Why is this bad?** Especially for big powers of 2 a hexadecimal representation is more
+    /// ### Why is this bad?
+    /// Especially for big powers of 2 a hexadecimal representation is more
     /// readable than a decimal representation.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// `255` => `0xFF`
     /// `65_535` => `0xFFFF`
     /// `4_042_322_160` => `0xF0F0_F0F0`
diff --git a/clippy_lints/src/loops/mod.rs b/clippy_lints/src/loops/mod.rs
index 56a123b69c6ae..7ca54d5397205 100644
--- a/clippy_lints/src/loops/mod.rs
+++ b/clippy_lints/src/loops/mod.rs
@@ -26,14 +26,14 @@ use rustc_span::source_map::Span;
 use utils::{get_span_of_entire_for_loop, make_iterator_snippet, IncrementVisitor, InitializeVisitor};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for for-loops that manually copy items between
+    /// ### What it does
+    /// Checks for for-loops that manually copy items between
     /// slices that could be optimized by having a memcpy.
     ///
-    /// **Why is this bad?** It is not as fast as a memcpy.
+    /// ### Why is this bad?
+    /// It is not as fast as a memcpy.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # let src = vec![1];
     /// # let mut dst = vec![0; 65];
@@ -53,15 +53,15 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for looping over the range of `0..len` of some
+    /// ### What it does
+    /// Checks for looping over the range of `0..len` of some
     /// collection just to get the values by index.
     ///
-    /// **Why is this bad?** Just iterating the collection itself makes the intent
+    /// ### Why is this bad?
+    /// Just iterating the collection itself makes the intent
     /// more clear and is probably faster.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// let vec = vec!['a', 'b', 'c'];
     /// for i in 0..vec.len() {
@@ -81,15 +81,18 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for loops on `x.iter()` where `&x` will do, and
+    /// ### What it does
+    /// Checks for loops on `x.iter()` where `&x` will do, and
     /// suggests the latter.
     ///
-    /// **Why is this bad?** Readability.
+    /// ### Why is this bad?
+    /// Readability.
     ///
-    /// **Known problems:** False negatives. We currently only warn on some known
+    /// ### Known problems
+    /// False negatives. We currently only warn on some known
     /// types.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// // with `y` a `Vec` or slice:
     /// # let y = vec![1];
@@ -110,14 +113,14 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for loops on `y.into_iter()` where `y` will do, and
+    /// ### What it does
+    /// Checks for loops on `y.into_iter()` where `y` will do, and
     /// suggests the latter.
     ///
-    /// **Why is this bad?** Readability.
+    /// ### Why is this bad?
+    /// Readability.
     ///
-    /// **Known problems:** None
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # let y = vec![1];
     /// // with `y` a `Vec` or slice:
@@ -138,18 +141,18 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for loops on `x.next()`.
+    /// ### What it does
+    /// Checks for loops on `x.next()`.
     ///
-    /// **Why is this bad?** `next()` returns either `Some(value)` if there was a
+    /// ### Why is this bad?
+    /// `next()` returns either `Some(value)` if there was a
     /// value, or `None` otherwise. The insidious thing is that `Option<_>`
     /// implements `IntoIterator`, so that possibly one value will be iterated,
     /// leading to some hard to find bugs. No one will want to write such code
     /// [except to win an Underhanded Rust
     /// Contest](https://www.reddit.com/r/rust/comments/3hb0wm/underhanded_rust_contest/cu5yuhr).
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```ignore
     /// for x in y.next() {
     ///     ..
@@ -161,14 +164,14 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for `for` loops over `Option` or `Result` values.
+    /// ### What it does
+    /// Checks for `for` loops over `Option` or `Result` values.
     ///
-    /// **Why is this bad?** Readability. This is more clearly expressed as an `if
+    /// ### Why is this bad?
+    /// Readability. This is more clearly expressed as an `if
     /// let`.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # let opt = Some(1);
     ///
@@ -204,15 +207,18 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Detects `loop + match` combinations that are easier
+    /// ### What it does
+    /// Detects `loop + match` combinations that are easier
     /// written as a `while let` loop.
     ///
-    /// **Why is this bad?** The `while let` loop is usually shorter and more
+    /// ### Why is this bad?
+    /// The `while let` loop is usually shorter and more
     /// readable.
     ///
-    /// **Known problems:** Sometimes the wrong binding is displayed ([#383](https://github.com/rust-lang/rust-clippy/issues/383)).
+    /// ### Known problems
+    /// Sometimes the wrong binding is displayed ([#383](https://github.com/rust-lang/rust-clippy/issues/383)).
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust,no_run
     /// # let y = Some(1);
     /// loop {
@@ -233,16 +239,15 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for functions collecting an iterator when collect
+    /// ### What it does
+    /// Checks for functions collecting an iterator when collect
     /// is not needed.
     ///
-    /// **Why is this bad?** `collect` causes the allocation of a new data structure,
+    /// ### Why is this bad?
+    /// `collect` causes the allocation of a new data structure,
     /// when this allocation may not be needed.
     ///
-    /// **Known problems:**
-    /// None
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # let iterator = vec![1].into_iter();
     /// let len = iterator.clone().collect::<Vec<_>>().len();
@@ -255,15 +260,15 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks `for` loops over slices with an explicit counter
+    /// ### What it does
+    /// Checks `for` loops over slices with an explicit counter
     /// and suggests the use of `.enumerate()`.
     ///
-    /// **Why is it bad?** Using `.enumerate()` makes the intent more clear,
+    /// ### Why is this bad?
+    /// Using `.enumerate()` makes the intent more clear,
     /// declutters the code and may be faster in some instances.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # let v = vec![1];
     /// # fn bar(bar: usize, baz: usize) {}
@@ -285,9 +290,11 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for empty `loop` expressions.
+    /// ### What it does
+    /// Checks for empty `loop` expressions.
     ///
-    /// **Why is this bad?** These busy loops burn CPU cycles without doing
+    /// ### Why is this bad?
+    /// These busy loops burn CPU cycles without doing
     /// anything. It is _almost always_ a better idea to `panic!` than to have
     /// a busy loop.
     ///
@@ -306,9 +313,7 @@ declare_clippy_lint! {
     ///   - [`x86_64::instructions::hlt`](https://docs.rs/x86_64/0.12.2/x86_64/instructions/fn.hlt.html)
     ///   - [`cortex_m::asm::wfi`](https://docs.rs/cortex-m/0.6.3/cortex_m/asm/fn.wfi.html)
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```no_run
     /// loop {}
     /// ```
@@ -318,14 +323,14 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for `while let` expressions on iterators.
+    /// ### What it does
+    /// Checks for `while let` expressions on iterators.
     ///
-    /// **Why is this bad?** Readability. A simple `for` loop is shorter and conveys
+    /// ### Why is this bad?
+    /// Readability. A simple `for` loop is shorter and conveys
     /// the intent better.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```ignore
     /// while let Some(val) = iter() {
     ///     ..
@@ -337,15 +342,15 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for iterating a map (`HashMap` or `BTreeMap`) and
+    /// ### What it does
+    /// Checks for iterating a map (`HashMap` or `BTreeMap`) and
     /// ignoring either the keys or values.
     ///
-    /// **Why is this bad?** Readability. There are `keys` and `values` methods that
+    /// ### Why is this bad?
+    /// Readability. There are `keys` and `values` methods that
     /// can be used to express that don't need the values or keys.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```ignore
     /// for (k, _) in &map {
     ///     ..
@@ -365,15 +370,15 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for loops that will always `break`, `return` or
+    /// ### What it does
+    /// Checks for loops that will always `break`, `return` or
     /// `continue` an outer loop.
     ///
-    /// **Why is this bad?** This loop never loops, all it does is obfuscating the
+    /// ### Why is this bad?
+    /// This loop never loops, all it does is obfuscating the
     /// code.
     ///
-    /// **Known problems:** None
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// loop {
     ///     ..;
@@ -386,13 +391,13 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for loops which have a range bound that is a mutable variable
-    ///
-    /// **Why is this bad?** One might think that modifying the mutable variable changes the loop bounds
+    /// ### What it does
+    /// Checks for loops which have a range bound that is a mutable variable
     ///
-    /// **Known problems:** None
+    /// ### Why is this bad?
+    /// One might think that modifying the mutable variable changes the loop bounds
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// let mut foo = 42;
     /// for i in 0..foo {
@@ -406,17 +411,20 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks whether variables used within while loop condition
+    /// ### What it does
+    /// Checks whether variables used within while loop condition
     /// can be (and are) mutated in the body.
     ///
-    /// **Why is this bad?** If the condition is unchanged, entering the body of the loop
+    /// ### Why is this bad?
+    /// If the condition is unchanged, entering the body of the loop
     /// will lead to an infinite loop.
     ///
-    /// **Known problems:** If the `while`-loop is in a closure, the check for mutation of the
+    /// ### Known problems
+    /// If the `while`-loop is in a closure, the check for mutation of the
     /// condition variables in the body can cause false negatives. For example when only `Upvar` `a` is
     /// in the condition and only `Upvar` `b` gets mutated in the body, the lint will not trigger.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// let i = 0;
     /// while i > 10 {
@@ -429,15 +437,16 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks whether a for loop is being used to push a constant
+    /// ### What it does
+    /// Checks whether a for loop is being used to push a constant
     /// value into a Vec.
     ///
-    /// **Why is this bad?** This kind of operation can be expressed more succinctly with
+    /// ### Why is this bad?
+    /// This kind of operation can be expressed more succinctly with
     /// `vec![item;SIZE]` or `vec.resize(NEW_SIZE, item)` and using these alternatives may also
     /// have better performance.
-    /// **Known problems:** None
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// let item1 = 2;
     /// let item2 = 3;
@@ -462,13 +471,14 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks whether a for loop has a single element.
+    /// ### What it does
+    /// Checks whether a for loop has a single element.
     ///
-    /// **Why is this bad?** There is no reason to have a loop of a
+    /// ### Why is this bad?
+    /// There is no reason to have a loop of a
     /// single element.
-    /// **Known problems:** None
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// let item1 = 2;
     /// for item in &[item1] {
@@ -487,15 +497,15 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Check for unnecessary `if let` usage in a for loop
+    /// ### What it does
+    /// Check for unnecessary `if let` usage in a for loop
     /// where only the `Some` or `Ok` variant of the iterator element is used.
     ///
-    /// **Why is this bad?** It is verbose and can be simplified
+    /// ### Why is this bad?
+    /// It is verbose and can be simplified
     /// by first calling the `flatten` method on the `Iterator`.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     ///
     /// ```rust
     /// let x = vec![Some(1), Some(2), Some(3)];
diff --git a/clippy_lints/src/macro_use.rs b/clippy_lints/src/macro_use.rs
index 66479ae264e4f..a371f8bbd3cb4 100644
--- a/clippy_lints/src/macro_use.rs
+++ b/clippy_lints/src/macro_use.rs
@@ -12,14 +12,14 @@ use rustc_session::{declare_tool_lint, impl_lint_pass};
 use rustc_span::{edition::Edition, sym, Span};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for `#[macro_use] use...`.
+    /// ### What it does
+    /// Checks for `#[macro_use] use...`.
     ///
-    /// **Why is this bad?** Since the Rust 2018 edition you can import
+    /// ### Why is this bad?
+    /// Since the Rust 2018 edition you can import
     /// macro's directly, this is considered idiomatic.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust,ignore
     /// #[macro_use]
     /// use some_macro;
diff --git a/clippy_lints/src/main_recursion.rs b/clippy_lints/src/main_recursion.rs
index 07d8a440aea4c..776e4b3fe768a 100644
--- a/clippy_lints/src/main_recursion.rs
+++ b/clippy_lints/src/main_recursion.rs
@@ -7,14 +7,14 @@ use rustc_lint::{LateContext, LateLintPass};
 use rustc_session::{declare_tool_lint, impl_lint_pass};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for recursion using the entrypoint.
+    /// ### What it does
+    /// Checks for recursion using the entrypoint.
     ///
-    /// **Why is this bad?** Apart from special setups (which we could detect following attributes like #![no_std]),
+    /// ### Why is this bad?
+    /// Apart from special setups (which we could detect following attributes like #![no_std]),
     /// recursing into main() seems like an unintuitive antipattern we should be able to detect.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```no_run
     /// fn main() {
     ///     main();
diff --git a/clippy_lints/src/manual_async_fn.rs b/clippy_lints/src/manual_async_fn.rs
index 5d88ff3b99f31..8e1385fb83a25 100644
--- a/clippy_lints/src/manual_async_fn.rs
+++ b/clippy_lints/src/manual_async_fn.rs
@@ -14,14 +14,13 @@ use rustc_session::{declare_lint_pass, declare_tool_lint};
 use rustc_span::{sym, Span};
 
 declare_clippy_lint! {
-    /// **What it does:** It checks for manual implementations of `async` functions.
+    /// ### What it does
+    /// It checks for manual implementations of `async` functions.
     ///
-    /// **Why is this bad?** It's more idiomatic to use the dedicated syntax.
-    ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Why is this bad?
+    /// It's more idiomatic to use the dedicated syntax.
     ///
+    /// ### Example
     /// ```rust
     /// use std::future::Future;
     ///
diff --git a/clippy_lints/src/manual_map.rs b/clippy_lints/src/manual_map.rs
index 563d5cdb5fb56..7dec1595e0d10 100644
--- a/clippy_lints/src/manual_map.rs
+++ b/clippy_lints/src/manual_map.rs
@@ -16,14 +16,13 @@ use rustc_session::{declare_lint_pass, declare_tool_lint};
 use rustc_span::{sym, SyntaxContext};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for usages of `match` which could be implemented using `map`
+    /// ### What it does
+    /// Checks for usages of `match` which could be implemented using `map`
     ///
-    /// **Why is this bad?** Using the `map` method is clearer and more concise.
-    ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Why is this bad?
+    /// Using the `map` method is clearer and more concise.
     ///
+    /// ### Example
     /// ```rust
     /// match Some(0) {
     ///     Some(x) => Some(x + 1),
diff --git a/clippy_lints/src/manual_non_exhaustive.rs b/clippy_lints/src/manual_non_exhaustive.rs
index 54f714b54b657..335ea001ee476 100644
--- a/clippy_lints/src/manual_non_exhaustive.rs
+++ b/clippy_lints/src/manual_non_exhaustive.rs
@@ -11,15 +11,14 @@ use rustc_session::{declare_tool_lint, impl_lint_pass};
 use rustc_span::{sym, Span};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for manual implementations of the non-exhaustive pattern.
+    /// ### What it does
+    /// Checks for manual implementations of the non-exhaustive pattern.
     ///
-    /// **Why is this bad?** Using the #[non_exhaustive] attribute expresses better the intent
+    /// ### Why is this bad?
+    /// Using the #[non_exhaustive] attribute expresses better the intent
     /// and allows possible optimizations when applied to enums.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust
     /// struct S {
     ///     pub a: i32,
diff --git a/clippy_lints/src/manual_ok_or.rs b/clippy_lints/src/manual_ok_or.rs
index 847c8c648b00a..b2f287af6971a 100644
--- a/clippy_lints/src/manual_ok_or.rs
+++ b/clippy_lints/src/manual_ok_or.rs
@@ -13,15 +13,15 @@ use rustc_session::{declare_lint_pass, declare_tool_lint};
 use rustc_span::symbol::sym;
 
 declare_clippy_lint! {
-    /// **What it does:**
+    /// ### What it does
+    ///
     /// Finds patterns that reimplement `Option::ok_or`.
     ///
-    /// **Why is this bad?**
-    /// Concise code helps focusing on behavior instead of boilerplate.
+    /// ### Why is this bad?
     ///
-    /// **Known problems:** None.
+    /// Concise code helps focusing on behavior instead of boilerplate.
     ///
-    /// **Examples:**
+    /// ### Examples
     /// ```rust
     /// let foo: Option<i32> = None;
     /// foo.map_or(Err("error"), |v| Ok(v));
diff --git a/clippy_lints/src/manual_strip.rs b/clippy_lints/src/manual_strip.rs
index 61b5fe81fa9e6..db12c377488b0 100644
--- a/clippy_lints/src/manual_strip.rs
+++ b/clippy_lints/src/manual_strip.rs
@@ -18,21 +18,17 @@ use rustc_span::source_map::Spanned;
 use rustc_span::Span;
 
 declare_clippy_lint! {
-    /// **What it does:**
+    /// ### What it does
     /// Suggests using `strip_{prefix,suffix}` over `str::{starts,ends}_with` and slicing using
     /// the pattern's length.
     ///
-    /// **Why is this bad?**
+    /// ### Why is this bad?
     /// Using `str:strip_{prefix,suffix}` is safer and may have better performance as there is no
     /// slicing which may panic and the compiler does not need to insert this panic code. It is
     /// also sometimes more readable as it removes the need for duplicating or storing the pattern
     /// used by `str::{starts,ends}_with` and in the slicing.
     ///
-    /// **Known problems:**
-    /// None.
-    ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust
     /// let s = "hello, world!";
     /// if s.starts_with("hello, ") {
diff --git a/clippy_lints/src/manual_unwrap_or.rs b/clippy_lints/src/manual_unwrap_or.rs
index 9d8d77cf8f089..426789742d51c 100644
--- a/clippy_lints/src/manual_unwrap_or.rs
+++ b/clippy_lints/src/manual_unwrap_or.rs
@@ -15,15 +15,13 @@ use rustc_session::{declare_lint_pass, declare_tool_lint};
 use rustc_span::sym;
 
 declare_clippy_lint! {
-    /// **What it does:**
+    /// ### What it does
     /// Finds patterns that reimplement `Option::unwrap_or` or `Result::unwrap_or`.
     ///
-    /// **Why is this bad?**
+    /// ### Why is this bad?
     /// Concise code helps focusing on behavior instead of boilerplate.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// let foo: Option<i32> = None;
     /// match foo {
diff --git a/clippy_lints/src/map_clone.rs b/clippy_lints/src/map_clone.rs
index e1f80ab025c0a..394606200bb04 100644
--- a/clippy_lints/src/map_clone.rs
+++ b/clippy_lints/src/map_clone.rs
@@ -15,16 +15,15 @@ use rustc_span::symbol::Ident;
 use rustc_span::{sym, Span};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for usage of `map(|x| x.clone())` or
+    /// ### What it does
+    /// Checks for usage of `map(|x| x.clone())` or
     /// dereferencing closures for `Copy` types, on `Iterator` or `Option`,
     /// and suggests `cloned()` or `copied()` instead
     ///
-    /// **Why is this bad?** Readability, this can be written more concisely
-    ///
-    /// **Known problems:** None
-    ///
-    /// **Example:**
+    /// ### Why is this bad?
+    /// Readability, this can be written more concisely
     ///
+    /// ### Example
     /// ```rust
     /// let x = vec![42, 43];
     /// let y = x.iter();
diff --git a/clippy_lints/src/map_err_ignore.rs b/clippy_lints/src/map_err_ignore.rs
index 425a9734e5fee..82d3732326ebb 100644
--- a/clippy_lints/src/map_err_ignore.rs
+++ b/clippy_lints/src/map_err_ignore.rs
@@ -4,13 +4,13 @@ use rustc_lint::{LateContext, LateLintPass};
 use rustc_session::{declare_lint_pass, declare_tool_lint};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for instances of `map_err(|_| Some::Enum)`
+    /// ### What it does
+    /// Checks for instances of `map_err(|_| Some::Enum)`
     ///
-    /// **Why is this bad?** This `map_err` throws away the original error rather than allowing the enum to contain and report the cause of the error
+    /// ### Why is this bad?
+    /// This `map_err` throws away the original error rather than allowing the enum to contain and report the cause of the error
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// Before:
     /// ```rust
     /// use std::fmt;
diff --git a/clippy_lints/src/map_unit_fn.rs b/clippy_lints/src/map_unit_fn.rs
index 57cd907e77e8d..fd40590d077ff 100644
--- a/clippy_lints/src/map_unit_fn.rs
+++ b/clippy_lints/src/map_unit_fn.rs
@@ -12,16 +12,15 @@ use rustc_span::source_map::Span;
 use rustc_span::sym;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for usage of `option.map(f)` where f is a function
+    /// ### What it does
+    /// Checks for usage of `option.map(f)` where f is a function
     /// or closure that returns the unit type `()`.
     ///
-    /// **Why is this bad?** Readability, this can be written more clearly with
+    /// ### Why is this bad?
+    /// Readability, this can be written more clearly with
     /// an if let statement
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust
     /// # fn do_stuff() -> Option<String> { Some(String::new()) }
     /// # fn log_err_msg(foo: String) -> Option<String> { Some(foo) }
@@ -54,16 +53,15 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for usage of `result.map(f)` where f is a function
+    /// ### What it does
+    /// Checks for usage of `result.map(f)` where f is a function
     /// or closure that returns the unit type `()`.
     ///
-    /// **Why is this bad?** Readability, this can be written more clearly with
+    /// ### Why is this bad?
+    /// Readability, this can be written more clearly with
     /// an if let statement
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust
     /// # fn do_stuff() -> Result<String, String> { Ok(String::new()) }
     /// # fn log_err_msg(foo: String) -> Result<String, String> { Ok(foo) }
diff --git a/clippy_lints/src/match_on_vec_items.rs b/clippy_lints/src/match_on_vec_items.rs
index ca6fb0831fe22..e66a35452f0d8 100644
--- a/clippy_lints/src/match_on_vec_items.rs
+++ b/clippy_lints/src/match_on_vec_items.rs
@@ -10,13 +10,13 @@ use rustc_session::{declare_lint_pass, declare_tool_lint};
 use rustc_span::sym;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for `match vec[idx]` or `match vec[n..m]`.
+    /// ### What it does
+    /// Checks for `match vec[idx]` or `match vec[n..m]`.
     ///
-    /// **Why is this bad?** This can panic at runtime.
+    /// ### Why is this bad?
+    /// This can panic at runtime.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust, no_run
     /// let arr = vec![0, 1, 2, 3];
     /// let idx = 1;
diff --git a/clippy_lints/src/matches.rs b/clippy_lints/src/matches.rs
index d7f600b3ab2b0..5360c02f90539 100644
--- a/clippy_lints/src/matches.rs
+++ b/clippy_lints/src/matches.rs
@@ -35,14 +35,14 @@ use std::iter;
 use std::ops::Bound;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for matches with a single arm where an `if let`
+    /// ### What it does
+    /// Checks for matches with a single arm where an `if let`
     /// will usually suffice.
     ///
-    /// **Why is this bad?** Just readability – `if let` nests less than a `match`.
+    /// ### Why is this bad?
+    /// Just readability – `if let` nests less than a `match`.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # fn bar(stool: &str) {}
     /// # let x = Some("abc");
@@ -63,15 +63,17 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for matches with two arms where an `if let else` will
+    /// ### What it does
+    /// Checks for matches with two arms where an `if let else` will
     /// usually suffice.
     ///
-    /// **Why is this bad?** Just readability – `if let` nests less than a `match`.
-    ///
-    /// **Known problems:** Personal style preferences may differ.
+    /// ### Why is this bad?
+    /// Just readability – `if let` nests less than a `match`.
     ///
-    /// **Example:**
+    /// ### Known problems
+    /// Personal style preferences may differ.
     ///
+    /// ### Example
     /// Using `match`:
     ///
     /// ```rust
@@ -102,16 +104,16 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for matches where all arms match a reference,
+    /// ### What it does
+    /// Checks for matches where all arms match a reference,
     /// suggesting to remove the reference and deref the matched expression
     /// instead. It also checks for `if let &foo = bar` blocks.
     ///
-    /// **Why is this bad?** It just makes the code less readable. That reference
+    /// ### Why is this bad?
+    /// It just makes the code less readable. That reference
     /// destructuring adds nothing to the code.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust,ignore
     /// // Bad
     /// match x {
@@ -133,14 +135,14 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for matches where match expression is a `bool`. It
+    /// ### What it does
+    /// Checks for matches where match expression is a `bool`. It
     /// suggests to replace the expression with an `if...else` block.
     ///
-    /// **Why is this bad?** It makes the code less readable.
+    /// ### Why is this bad?
+    /// It makes the code less readable.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # fn foo() {}
     /// # fn bar() {}
@@ -167,14 +169,14 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for overlapping match arms.
+    /// ### What it does
+    /// Checks for overlapping match arms.
     ///
-    /// **Why is this bad?** It is likely to be an error and if not, makes the code
+    /// ### Why is this bad?
+    /// It is likely to be an error and if not, makes the code
     /// less obvious.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// let x = 5;
     /// match x {
@@ -189,15 +191,15 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for arm which matches all errors with `Err(_)`
+    /// ### What it does
+    /// Checks for arm which matches all errors with `Err(_)`
     /// and take drastic actions like `panic!`.
     ///
-    /// **Why is this bad?** It is generally a bad practice, similar to
+    /// ### Why is this bad?
+    /// It is generally a bad practice, similar to
     /// catching all exceptions in java with `catch(Exception)`
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// let x: Result<i32, &str> = Ok(3);
     /// match x {
@@ -211,14 +213,14 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for match which is used to add a reference to an
+    /// ### What it does
+    /// Checks for match which is used to add a reference to an
     /// `Option` value.
     ///
-    /// **Why is this bad?** Using `as_ref()` or `as_mut()` instead is shorter.
+    /// ### Why is this bad?
+    /// Using `as_ref()` or `as_mut()` instead is shorter.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// let x: Option<()> = None;
     ///
@@ -237,14 +239,17 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for wildcard enum matches using `_`.
+    /// ### What it does
+    /// Checks for wildcard enum matches using `_`.
     ///
-    /// **Why is this bad?** New enum variants added by library updates can be missed.
+    /// ### Why is this bad?
+    /// New enum variants added by library updates can be missed.
     ///
-    /// **Known problems:** Suggested replacements may be incorrect if guards exhaustively cover some
+    /// ### Known problems
+    /// Suggested replacements may be incorrect if guards exhaustively cover some
     /// variants, and also may not use correct path to enum if it's not present in the current scope.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # enum Foo { A(usize), B(usize) }
     /// # let x = Foo::B(1);
@@ -266,15 +271,17 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for wildcard enum matches for a single variant.
+    /// ### What it does
+    /// Checks for wildcard enum matches for a single variant.
     ///
-    /// **Why is this bad?** New enum variants added by library updates can be missed.
+    /// ### Why is this bad?
+    /// New enum variants added by library updates can be missed.
     ///
-    /// **Known problems:** Suggested replacements may not use correct path to enum
+    /// ### Known problems
+    /// Suggested replacements may not use correct path to enum
     /// if it's not present in the current scope.
     ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust
     /// # enum Foo { A, B, C }
     /// # let x = Foo::B;
@@ -298,14 +305,14 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for wildcard pattern used with others patterns in same match arm.
+    /// ### What it does
+    /// Checks for wildcard pattern used with others patterns in same match arm.
     ///
-    /// **Why is this bad?** Wildcard pattern already covers any other pattern as it will match anyway.
+    /// ### Why is this bad?
+    /// Wildcard pattern already covers any other pattern as it will match anyway.
     /// It makes the code less readable, especially to spot wildcard pattern use in match arm.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// // Bad
     /// match "foo" {
@@ -325,14 +332,14 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for matches being used to destructure a single-variant enum
+    /// ### What it does
+    /// Checks for matches being used to destructure a single-variant enum
     /// or tuple struct where a `let` will suffice.
     ///
-    /// **Why is this bad?** Just readability – `let` doesn't nest, whereas a `match` does.
+    /// ### Why is this bad?
+    /// Just readability – `let` doesn't nest, whereas a `match` does.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// enum Wrapper {
     ///     Data(i32),
@@ -360,14 +367,17 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for useless match that binds to only one value.
+    /// ### What it does
+    /// Checks for useless match that binds to only one value.
     ///
-    /// **Why is this bad?** Readability and needless complexity.
+    /// ### Why is this bad?
+    /// Readability and needless complexity.
     ///
-    /// **Known problems:**  Suggested replacements may be incorrect when `match`
+    /// ### Known problems
+    ///  Suggested replacements may be incorrect when `match`
     /// is actually binding temporary value, bringing a 'dropped while borrowed' error.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # let a = 1;
     /// # let b = 2;
@@ -388,14 +398,14 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for unnecessary '..' pattern binding on struct when all fields are explicitly matched.
+    /// ### What it does
+    /// Checks for unnecessary '..' pattern binding on struct when all fields are explicitly matched.
     ///
-    /// **Why is this bad?** Correctness and readability. It's like having a wildcard pattern after
+    /// ### Why is this bad?
+    /// Correctness and readability. It's like having a wildcard pattern after
     /// matching all enum variants explicitly.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # struct A { a: i32 }
     /// let a = A { a: 5 };
@@ -418,21 +428,23 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Lint for redundant pattern matching over `Result`, `Option`,
+    /// ### What it does
+    /// Lint for redundant pattern matching over `Result`, `Option`,
     /// `std::task::Poll` or `std::net::IpAddr`
     ///
-    /// **Why is this bad?** It's more concise and clear to just use the proper
+    /// ### Why is this bad?
+    /// It's more concise and clear to just use the proper
     /// utility function
     ///
-    /// **Known problems:** This will change the drop order for the matched type. Both `if let` and
+    /// ### Known problems
+    /// This will change the drop order for the matched type. Both `if let` and
     /// `while let` will drop the value at the end of the block, both `if` and `while` will drop the
     /// value before entering the block. For most types this change will not matter, but for a few
     /// types this will not be an acceptable change (e.g. locks). See the
     /// [reference](https://doc.rust-lang.org/reference/destructors.html#drop-scopes) for more about
     /// drop order.
     ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust
     /// # use std::task::Poll;
     /// # use std::net::{IpAddr, Ipv4Addr, Ipv6Addr};
@@ -471,15 +483,18 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for `match`  or `if let` expressions producing a
+    /// ### What it does
+    /// Checks for `match`  or `if let` expressions producing a
     /// `bool` that could be written using `matches!`
     ///
-    /// **Why is this bad?** Readability and needless complexity.
+    /// ### Why is this bad?
+    /// Readability and needless complexity.
     ///
-    /// **Known problems:** This lint falsely triggers, if there are arms with
+    /// ### Known problems
+    /// This lint falsely triggers, if there are arms with
     /// `cfg` attributes that remove an arm evaluating to `false`.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// let x = Some(5);
     ///
@@ -504,17 +519,20 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for `match` with identical arm bodies.
+    /// ### What it does
+    /// Checks for `match` with identical arm bodies.
     ///
-    /// **Why is this bad?** This is probably a copy & paste error. If arm bodies
+    /// ### Why is this bad?
+    /// This is probably a copy & paste error. If arm bodies
     /// are the same on purpose, you can factor them
     /// [using `|`](https://doc.rust-lang.org/book/patterns.html#multiple-patterns).
     ///
-    /// **Known problems:** False positive possible with order dependent `match`
+    /// ### Known problems
+    /// False positive possible with order dependent `match`
     /// (see issue
     /// [#860](https://github.com/rust-lang/rust-clippy/issues/860)).
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust,ignore
     /// match foo {
     ///     Bar => bar(),
diff --git a/clippy_lints/src/mem_discriminant.rs b/clippy_lints/src/mem_discriminant.rs
index aca96e06ef2e7..59176c4b84663 100644
--- a/clippy_lints/src/mem_discriminant.rs
+++ b/clippy_lints/src/mem_discriminant.rs
@@ -9,14 +9,14 @@ use rustc_lint::{LateContext, LateLintPass};
 use rustc_session::{declare_lint_pass, declare_tool_lint};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for calls of `mem::discriminant()` on a non-enum type.
+    /// ### What it does
+    /// Checks for calls of `mem::discriminant()` on a non-enum type.
     ///
-    /// **Why is this bad?** The value of `mem::discriminant()` on non-enum types
+    /// ### Why is this bad?
+    /// The value of `mem::discriminant()` on non-enum types
     /// is unspecified.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// use std::mem;
     ///
diff --git a/clippy_lints/src/mem_forget.rs b/clippy_lints/src/mem_forget.rs
index a28cb5f32fe8a..07202a59c4b96 100644
--- a/clippy_lints/src/mem_forget.rs
+++ b/clippy_lints/src/mem_forget.rs
@@ -5,15 +5,15 @@ use rustc_lint::{LateContext, LateLintPass};
 use rustc_session::{declare_lint_pass, declare_tool_lint};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for usage of `std::mem::forget(t)` where `t` is
+    /// ### What it does
+    /// Checks for usage of `std::mem::forget(t)` where `t` is
     /// `Drop`.
     ///
-    /// **Why is this bad?** `std::mem::forget(t)` prevents `t` from running its
+    /// ### Why is this bad?
+    /// `std::mem::forget(t)` prevents `t` from running its
     /// destructor, possibly causing leaks.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # use std::mem;
     /// # use std::rc::Rc;
diff --git a/clippy_lints/src/mem_replace.rs b/clippy_lints/src/mem_replace.rs
index 183daee361774..3d071c9081be1 100644
--- a/clippy_lints/src/mem_replace.rs
+++ b/clippy_lints/src/mem_replace.rs
@@ -14,16 +14,16 @@ use rustc_span::source_map::Span;
 use rustc_span::symbol::sym;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for `mem::replace()` on an `Option` with
+    /// ### What it does
+    /// Checks for `mem::replace()` on an `Option` with
     /// `None`.
     ///
-    /// **Why is this bad?** `Option` already has the method `take()` for
+    /// ### Why is this bad?
+    /// `Option` already has the method `take()` for
     /// taking its current value (Some(..) or None) and replacing it with
     /// `None`.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// use std::mem;
     ///
@@ -41,17 +41,16 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for `mem::replace(&mut _, mem::uninitialized())`
+    /// ### What it does
+    /// Checks for `mem::replace(&mut _, mem::uninitialized())`
     /// and `mem::replace(&mut _, mem::zeroed())`.
     ///
-    /// **Why is this bad?** This will lead to undefined behavior even if the
+    /// ### Why is this bad?
+    /// This will lead to undefined behavior even if the
     /// value is overwritten later, because the uninitialized value may be
     /// observed in the case of a panic.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```
     /// use std::mem;
     ///# fn may_panic(v: Vec<i32>) -> Vec<i32> { v }
@@ -73,15 +72,15 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for `std::mem::replace` on a value of type
+    /// ### What it does
+    /// Checks for `std::mem::replace` on a value of type
     /// `T` with `T::default()`.
     ///
-    /// **Why is this bad?** `std::mem` module already has the method `take` to
+    /// ### Why is this bad?
+    /// `std::mem` module already has the method `take` to
     /// take the current value and replace it with the default value of that type.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// let mut text = String::from("foo");
     /// let replaced = std::mem::replace(&mut text, String::default());
diff --git a/clippy_lints/src/methods/mod.rs b/clippy_lints/src/methods/mod.rs
index 283fcf281df18..d3e120238141e 100644
--- a/clippy_lints/src/methods/mod.rs
+++ b/clippy_lints/src/methods/mod.rs
@@ -80,16 +80,15 @@ use rustc_span::{sym, Span};
 use rustc_typeck::hir_ty_to_ty;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for usages of `cloned()` on an `Iterator` or `Option` where
+    /// ### What it does
+    /// Checks for usages of `cloned()` on an `Iterator` or `Option` where
     /// `copied()` could be used instead.
     ///
-    /// **Why is this bad?** `copied()` is better because it guarantees that the type being cloned
+    /// ### Why is this bad?
+    /// `copied()` is better because it guarantees that the type being cloned
     /// implements `Copy`.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust
     /// [1, 2, 3].iter().cloned();
     /// ```
@@ -103,16 +102,15 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for usages of `Iterator::flat_map()` where `filter_map()` could be
+    /// ### What it does
+    /// Checks for usages of `Iterator::flat_map()` where `filter_map()` could be
     /// used instead.
     ///
-    /// **Why is this bad?** When applicable, `filter_map()` is more clear since it shows that
+    /// ### Why is this bad?
+    /// When applicable, `filter_map()` is more clear since it shows that
     /// `Option` is used to produce 0 or 1 items.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust
     /// let nums: Vec<i32> = ["1", "2", "whee!"].iter().flat_map(|x| x.parse().ok()).collect();
     /// ```
@@ -126,9 +124,11 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for `.unwrap()` calls on `Option`s and on `Result`s.
+    /// ### What it does
+    /// Checks for `.unwrap()` calls on `Option`s and on `Result`s.
     ///
-    /// **Why is this bad?** It is better to handle the `None` or `Err` case,
+    /// ### Why is this bad?
+    /// It is better to handle the `None` or `Err` case,
     /// or at least call `.expect(_)` with a more helpful message. Still, for a lot of
     /// quick-and-dirty code, `unwrap` is a good choice, which is why this lint is
     /// `Allow` by default.
@@ -141,9 +141,7 @@ declare_clippy_lint! {
     /// messages on display. Therefore, it may be beneficial to look at the places
     /// where they may get displayed. Activate this lint to do just that.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Examples:**
+    /// ### Examples
     /// ```rust
     /// # let opt = Some(1);
     ///
@@ -171,9 +169,11 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for `.expect()` calls on `Option`s and `Result`s.
+    /// ### What it does
+    /// Checks for `.expect()` calls on `Option`s and `Result`s.
     ///
-    /// **Why is this bad?** Usually it is better to handle the `None` or `Err` case.
+    /// ### Why is this bad?
+    /// Usually it is better to handle the `None` or `Err` case.
     /// Still, for a lot of quick-and-dirty code, `expect` is a good choice, which is why
     /// this lint is `Allow` by default.
     ///
@@ -181,9 +181,7 @@ declare_clippy_lint! {
     /// values. Normally, you want to implement more sophisticated error handling,
     /// and propagate errors upwards with `?` operator.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Examples:**
+    /// ### Examples
     /// ```rust,ignore
     /// # let opt = Some(1);
     ///
@@ -213,20 +211,20 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for methods that should live in a trait
+    /// ### What it does
+    /// Checks for methods that should live in a trait
     /// implementation of a `std` trait (see [llogiq's blog
     /// post](http://llogiq.github.io/2015/07/30/traits.html) for further
     /// information) instead of an inherent implementation.
     ///
-    /// **Why is this bad?** Implementing the traits improve ergonomics for users of
+    /// ### Why is this bad?
+    /// Implementing the traits improve ergonomics for users of
     /// the code, often with very little cost. Also people seeing a `mul(...)`
     /// method
     /// may expect `*` to work equally, so you should have good reason to disappoint
     /// them.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// struct X;
     /// impl X {
@@ -242,7 +240,8 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for methods with certain name prefixes and which
+    /// ### What it does
+    /// Checks for methods with certain name prefixes and which
     /// doesn't match how self is taken. The actual rules are:
     ///
     /// |Prefix |Postfix     |`self` taken           | `self` type  |
@@ -265,13 +264,12 @@ declare_clippy_lint! {
     /// Please find more info here:
     /// https://rust-lang.github.io/api-guidelines/naming.html#ad-hoc-conversions-follow-as_-to_-into_-conventions-c-conv
     ///
-    /// **Why is this bad?** Consistency breeds readability. If you follow the
+    /// ### Why is this bad?
+    /// Consistency breeds readability. If you follow the
     /// conventions, your users won't be surprised that they, e.g., need to supply a
     /// mutable reference to a `as_..` function.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # struct X;
     /// impl X {
@@ -287,14 +285,17 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for usage of `ok().expect(..)`.
+    /// ### What it does
+    /// Checks for usage of `ok().expect(..)`.
     ///
-    /// **Why is this bad?** Because you usually call `expect()` on the `Result`
+    /// ### Why is this bad?
+    /// Because you usually call `expect()` on the `Result`
     /// directly to get a better error message.
     ///
-    /// **Known problems:** The error type needs to implement `Debug`
+    /// ### Known problems
+    /// The error type needs to implement `Debug`
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # let x = Ok::<_, ()>(());
     ///
@@ -310,15 +311,18 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for usage of `option.map(_).unwrap_or(_)` or `option.map(_).unwrap_or_else(_)` or
+    /// ### What it does
+    /// Checks for usage of `option.map(_).unwrap_or(_)` or `option.map(_).unwrap_or_else(_)` or
     /// `result.map(_).unwrap_or_else(_)`.
     ///
-    /// **Why is this bad?** Readability, these can be written more concisely (resp.) as
+    /// ### Why is this bad?
+    /// Readability, these can be written more concisely (resp.) as
     /// `option.map_or(_, _)`, `option.map_or_else(_, _)` and `result.map_or_else(_, _)`.
     ///
-    /// **Known problems:** The order of the arguments is not in execution order
+    /// ### Known problems
+    /// The order of the arguments is not in execution order
     ///
-    /// **Examples:**
+    /// ### Examples
     /// ```rust
     /// # let x = Some(1);
     ///
@@ -347,14 +351,17 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for usage of `_.map_or(None, _)`.
+    /// ### What it does
+    /// Checks for usage of `_.map_or(None, _)`.
     ///
-    /// **Why is this bad?** Readability, this can be written more concisely as
+    /// ### Why is this bad?
+    /// Readability, this can be written more concisely as
     /// `_.and_then(_)`.
     ///
-    /// **Known problems:** The order of the arguments is not in execution order.
+    /// ### Known problems
+    /// The order of the arguments is not in execution order.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # let opt = Some(1);
     ///
@@ -370,15 +377,14 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for usage of `_.map_or(None, Some)`.
+    /// ### What it does
+    /// Checks for usage of `_.map_or(None, Some)`.
     ///
-    /// **Why is this bad?** Readability, this can be written more concisely as
+    /// ### Why is this bad?
+    /// Readability, this can be written more concisely as
     /// `_.ok()`.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// Bad:
     /// ```rust
     /// # let r: Result<u32, &str> = Ok(1);
@@ -396,16 +402,15 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for usage of `_.and_then(|x| Some(y))`, `_.and_then(|x| Ok(y))` or
+    /// ### What it does
+    /// Checks for usage of `_.and_then(|x| Some(y))`, `_.and_then(|x| Ok(y))` or
     /// `_.or_else(|x| Err(y))`.
     ///
-    /// **Why is this bad?** Readability, this can be written more concisely as
+    /// ### Why is this bad?
+    /// Readability, this can be written more concisely as
     /// `_.map(|x| y)` or `_.map_err(|x| y)`.
     ///
-    /// **Known problems:** None
-    ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust
     /// # fn opt() -> Option<&'static str> { Some("42") }
     /// # fn res() -> Result<&'static str, &'static str> { Ok("42") }
@@ -429,14 +434,14 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for usage of `_.filter(_).next()`.
+    /// ### What it does
+    /// Checks for usage of `_.filter(_).next()`.
     ///
-    /// **Why is this bad?** Readability, this can be written more concisely as
+    /// ### Why is this bad?
+    /// Readability, this can be written more concisely as
     /// `_.find(_)`.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # let vec = vec![1];
     /// vec.iter().filter(|x| **x == 0).next();
@@ -452,14 +457,14 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for usage of `_.skip_while(condition).next()`.
+    /// ### What it does
+    /// Checks for usage of `_.skip_while(condition).next()`.
     ///
-    /// **Why is this bad?** Readability, this can be written more concisely as
+    /// ### Why is this bad?
+    /// Readability, this can be written more concisely as
     /// `_.find(!condition)`.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # let vec = vec![1];
     /// vec.iter().skip_while(|x| **x == 0).next();
@@ -475,14 +480,14 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for usage of `_.map(_).flatten(_)` on `Iterator` and `Option`
+    /// ### What it does
+    /// Checks for usage of `_.map(_).flatten(_)` on `Iterator` and `Option`
     ///
-    /// **Why is this bad?** Readability, this can be written more concisely as
+    /// ### Why is this bad?
+    /// Readability, this can be written more concisely as
     /// `_.flat_map(_)`
     ///
-    /// **Known problems:**
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// let vec = vec![vec![1]];
     ///
@@ -498,15 +503,15 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for usage of `_.filter(_).map(_)` that can be written more simply
+    /// ### What it does
+    /// Checks for usage of `_.filter(_).map(_)` that can be written more simply
     /// as `filter_map(_)`.
     ///
-    /// **Why is this bad?** Redundant code in the `filter` and `map` operations is poor style and
+    /// ### Why is this bad?
+    /// Redundant code in the `filter` and `map` operations is poor style and
     /// less performant.
     ///
-    /// **Known problems:** None.
-    ///
-     /// **Example:**
+     /// ### Example
     /// Bad:
     /// ```rust
     /// (0_i32..10)
@@ -524,15 +529,15 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for usage of `_.find(_).map(_)` that can be written more simply
+    /// ### What it does
+    /// Checks for usage of `_.find(_).map(_)` that can be written more simply
     /// as `find_map(_)`.
     ///
-    /// **Why is this bad?** Redundant code in the `find` and `map` operations is poor style and
+    /// ### Why is this bad?
+    /// Redundant code in the `find` and `map` operations is poor style and
     /// less performant.
     ///
-    /// **Known problems:** None.
-    ///
-     /// **Example:**
+     /// ### Example
     /// Bad:
     /// ```rust
     /// (0_i32..10)
@@ -550,14 +555,14 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for usage of `_.filter_map(_).next()`.
+    /// ### What it does
+    /// Checks for usage of `_.filter_map(_).next()`.
     ///
-    /// **Why is this bad?** Readability, this can be written more concisely as
+    /// ### Why is this bad?
+    /// Readability, this can be written more concisely as
     /// `_.find_map(_)`.
     ///
-    /// **Known problems:** None
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     ///  (0..3).filter_map(|x| if x == 2 { Some(x) } else { None }).next();
     /// ```
@@ -572,13 +577,13 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for usage of `flat_map(|x| x)`.
+    /// ### What it does
+    /// Checks for usage of `flat_map(|x| x)`.
     ///
-    /// **Why is this bad?** Readability, this can be written more concisely by using `flatten`.
+    /// ### Why is this bad?
+    /// Readability, this can be written more concisely by using `flatten`.
     ///
-    /// **Known problems:** None
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # let iter = vec![vec![0]].into_iter();
     /// iter.flat_map(|x| x);
@@ -594,16 +599,16 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for an iterator or string search (such as `find()`,
+    /// ### What it does
+    /// Checks for an iterator or string search (such as `find()`,
     /// `position()`, or `rposition()`) followed by a call to `is_some()` or `is_none()`.
     ///
-    /// **Why is this bad?** Readability, this can be written more concisely as:
+    /// ### Why is this bad?
+    /// Readability, this can be written more concisely as:
     /// * `_.any(_)`, or `_.contains(_)` for `is_some()`,
     /// * `!_.any(_)`, or `!_.contains(_)` for `is_none()`.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// let vec = vec![1];
     /// vec.iter().find(|x| **x == 0).is_some();
@@ -623,15 +628,15 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for usage of `.chars().next()` on a `str` to check
+    /// ### What it does
+    /// Checks for usage of `.chars().next()` on a `str` to check
     /// if it starts with a given char.
     ///
-    /// **Why is this bad?** Readability, this can be written more concisely as
+    /// ### Why is this bad?
+    /// Readability, this can be written more concisely as
     /// `_.starts_with(_)`.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// let name = "foo";
     /// if name.chars().next() == Some('_') {};
@@ -647,17 +652,20 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for calls to `.or(foo(..))`, `.unwrap_or(foo(..))`,
+    /// ### What it does
+    /// Checks for calls to `.or(foo(..))`, `.unwrap_or(foo(..))`,
     /// etc., and suggests to use `or_else`, `unwrap_or_else`, etc., or
     /// `unwrap_or_default` instead.
     ///
-    /// **Why is this bad?** The function will always be called and potentially
+    /// ### Why is this bad?
+    /// The function will always be called and potentially
     /// allocate an object acting as the default.
     ///
-    /// **Known problems:** If the function has side-effects, not calling it will
+    /// ### Known problems
+    /// If the function has side-effects, not calling it will
     /// change the semantic of the program, but you shouldn't rely on that anyway.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # let foo = Some(String::new());
     /// foo.unwrap_or(String::new());
@@ -678,15 +686,18 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for calls to `.expect(&format!(...))`, `.expect(foo(..))`,
+    /// ### What it does
+    /// Checks for calls to `.expect(&format!(...))`, `.expect(foo(..))`,
     /// etc., and suggests to use `unwrap_or_else` instead
     ///
-    /// **Why is this bad?** The function will always be called.
+    /// ### Why is this bad?
+    /// The function will always be called.
     ///
-    /// **Known problems:** If the function has side-effects, not calling it will
+    /// ### Known problems
+    /// If the function has side-effects, not calling it will
     /// change the semantics of the program, but you shouldn't rely on that anyway.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # let foo = Some(String::new());
     /// # let err_code = "418";
@@ -713,14 +724,14 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for usage of `.clone()` on a `Copy` type.
+    /// ### What it does
+    /// Checks for usage of `.clone()` on a `Copy` type.
     ///
-    /// **Why is this bad?** The only reason `Copy` types implement `Clone` is for
+    /// ### Why is this bad?
+    /// The only reason `Copy` types implement `Clone` is for
     /// generics, not for using the `clone` method on a concrete type.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// 42u64.clone();
     /// ```
@@ -730,15 +741,17 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for usage of `.clone()` on a ref-counted pointer,
+    /// ### What it does
+    /// Checks for usage of `.clone()` on a ref-counted pointer,
     /// (`Rc`, `Arc`, `rc::Weak`, or `sync::Weak`), and suggests calling Clone via unified
     /// function syntax instead (e.g., `Rc::clone(foo)`).
     ///
-    /// **Why is this bad?** Calling '.clone()' on an Rc, Arc, or Weak
+    /// ### Why is this bad?
+    /// Calling '.clone()' on an Rc, Arc, or Weak
     /// can obscure the fact that only the pointer is being cloned, not the underlying
     /// data.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # use std::rc::Rc;
     /// let x = Rc::new(1);
@@ -755,14 +768,14 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for usage of `.clone()` on an `&&T`.
+    /// ### What it does
+    /// Checks for usage of `.clone()` on an `&&T`.
     ///
-    /// **Why is this bad?** Cloning an `&&T` copies the inner `&T`, instead of
+    /// ### Why is this bad?
+    /// Cloning an `&&T` copies the inner `&T`, instead of
     /// cloning the underlying `T`.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// fn main() {
     ///     let x = vec![1];
@@ -777,16 +790,16 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for usage of `.to_string()` on an `&&T` where
+    /// ### What it does
+    /// Checks for usage of `.to_string()` on an `&&T` where
     /// `T` implements `ToString` directly (like `&&str` or `&&String`).
     ///
-    /// **Why is this bad?** This bypasses the specialized implementation of
+    /// ### Why is this bad?
+    /// This bypasses the specialized implementation of
     /// `ToString` and instead goes through the more expensive string formatting
     /// facilities.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// // Generic implementation for `T: Display` is used (slow)
     /// ["foo", "bar"].iter().map(|s| s.to_string());
@@ -800,14 +813,14 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for `new` not returning a type that contains `Self`.
+    /// ### What it does
+    /// Checks for `new` not returning a type that contains `Self`.
     ///
-    /// **Why is this bad?** As a convention, `new` methods are used to make a new
+    /// ### Why is this bad?
+    /// As a convention, `new` methods are used to make a new
     /// instance of a type.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// In an impl block:
     /// ```rust
     /// # struct Foo;
@@ -861,15 +874,18 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for string methods that receive a single-character
+    /// ### What it does
+    /// Checks for string methods that receive a single-character
     /// `str` as an argument, e.g., `_.split("x")`.
     ///
-    /// **Why is this bad?** Performing these methods using a `char` is faster than
+    /// ### Why is this bad?
+    /// Performing these methods using a `char` is faster than
     /// using a `str`.
     ///
-    /// **Known problems:** Does not catch multi-byte unicode characters.
+    /// ### Known problems
+    /// Does not catch multi-byte unicode characters.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust,ignore
     /// // Bad
     /// _.split("x");
@@ -882,14 +898,14 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for calling `.step_by(0)` on iterators which panics.
+    /// ### What it does
+    /// Checks for calling `.step_by(0)` on iterators which panics.
     ///
-    /// **Why is this bad?** This very much looks like an oversight. Use `panic!()` instead if you
+    /// ### Why is this bad?
+    /// This very much looks like an oversight. Use `panic!()` instead if you
     /// actually intend to panic.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust,should_panic
     /// for x in (0..100).step_by(0) {
     ///     //..
@@ -901,15 +917,14 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for indirect collection of populated `Option`
+    /// ### What it does
+    /// Checks for indirect collection of populated `Option`
     ///
-    /// **Why is this bad?** `Option` is like a collection of 0-1 things, so `flatten`
+    /// ### Why is this bad?
+    /// `Option` is like a collection of 0-1 things, so `flatten`
     /// automatically does this without suspicious-looking `unwrap` calls.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust
     /// let _ = std::iter::empty::<Option<i32>>().filter(Option::is_some).map(Option::unwrap);
     /// ```
@@ -923,16 +938,15 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for the use of `iter.nth(0)`.
+    /// ### What it does
+    /// Checks for the use of `iter.nth(0)`.
     ///
-    /// **Why is this bad?** `iter.next()` is equivalent to
+    /// ### Why is this bad?
+    /// `iter.next()` is equivalent to
     /// `iter.nth(0)`, as they both consume the next element,
     ///  but is more readable.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust
     /// # use std::collections::HashSet;
     /// // Bad
@@ -951,15 +965,15 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for use of `.iter().nth()` (and the related
+    /// ### What it does
+    /// Checks for use of `.iter().nth()` (and the related
     /// `.iter_mut().nth()`) on standard library types with O(1) element access.
     ///
-    /// **Why is this bad?** `.get()` and `.get_mut()` are more efficient and more
+    /// ### Why is this bad?
+    /// `.get()` and `.get_mut()` are more efficient and more
     /// readable.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// let some_vec = vec![0, 1, 2, 3];
     /// let bad_vec = some_vec.iter().nth(3);
@@ -977,13 +991,13 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for use of `.skip(x).next()` on iterators.
-    ///
-    /// **Why is this bad?** `.nth(x)` is cleaner
+    /// ### What it does
+    /// Checks for use of `.skip(x).next()` on iterators.
     ///
-    /// **Known problems:** None.
+    /// ### Why is this bad?
+    /// `.nth(x)` is cleaner
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// let some_vec = vec![0, 1, 2, 3];
     /// let bad_vec = some_vec.iter().skip(3).next();
@@ -1001,13 +1015,16 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for use of `.get().unwrap()` (or
+    /// ### What it does
+    /// Checks for use of `.get().unwrap()` (or
     /// `.get_mut().unwrap`) on a standard library type which implements `Index`
     ///
-    /// **Why is this bad?** Using the Index trait (`[]`) is more clear and more
+    /// ### Why is this bad?
+    /// Using the Index trait (`[]`) is more clear and more
     /// concise.
     ///
-    /// **Known problems:** Not a replacement for error handling: Using either
+    /// ### Known problems
+    /// Not a replacement for error handling: Using either
     /// `.unwrap()` or the Index trait (`[]`) carries the risk of causing a `panic`
     /// if the value being accessed is `None`. If the use of `.get().unwrap()` is a
     /// temporary placeholder for dealing with the `Option` type, then this does
@@ -1016,7 +1033,7 @@ declare_clippy_lint! {
     /// is handled in a future refactor instead of using `.unwrap()` or the Index
     /// trait.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// let mut some_vec = vec![0, 1, 2, 3];
     /// let last = some_vec.get(3).unwrap();
@@ -1034,14 +1051,13 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for occurrences where one vector gets extended instead of append
+    /// ### What it does
+    /// Checks for occurrences where one vector gets extended instead of append
     ///
-    /// **Why is this bad?** Using `append` instead of `extend` is more concise and faster
-    ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Why is this bad?
+    /// Using `append` instead of `extend` is more concise and faster
     ///
+    /// ### Example
     /// ```rust
     /// let mut a = vec![1, 2, 3];
     /// let mut b = vec![4, 5, 6];
@@ -1058,14 +1074,14 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for the use of `.extend(s.chars())` where s is a
+    /// ### What it does
+    /// Checks for the use of `.extend(s.chars())` where s is a
     /// `&str` or `String`.
     ///
-    /// **Why is this bad?** `.push_str(s)` is clearer
+    /// ### Why is this bad?
+    /// `.push_str(s)` is clearer
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// let abc = "abc";
     /// let def = String::from("def");
@@ -1087,14 +1103,14 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for the use of `.cloned().collect()` on slice to
+    /// ### What it does
+    /// Checks for the use of `.cloned().collect()` on slice to
     /// create a `Vec`.
     ///
-    /// **Why is this bad?** `.to_vec()` is clearer
-    ///
-    /// **Known problems:** None.
+    /// ### Why is this bad?
+    /// `.to_vec()` is clearer
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// let s = [1, 2, 3, 4, 5];
     /// let s2: Vec<isize> = s[..].iter().cloned().collect();
@@ -1110,15 +1126,15 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for usage of `_.chars().last()` or
+    /// ### What it does
+    /// Checks for usage of `_.chars().last()` or
     /// `_.chars().next_back()` on a `str` to check if it ends with a given char.
     ///
-    /// **Why is this bad?** Readability, this can be written more concisely as
+    /// ### Why is this bad?
+    /// Readability, this can be written more concisely as
     /// `_.ends_with(_)`.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # let name = "_";
     ///
@@ -1134,14 +1150,14 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for usage of `.as_ref()` or `.as_mut()` where the
+    /// ### What it does
+    /// Checks for usage of `.as_ref()` or `.as_mut()` where the
     /// types before and after the call are the same.
     ///
-    /// **Why is this bad?** The call is unnecessary.
-    ///
-    /// **Known problems:** None.
+    /// ### Why is this bad?
+    /// The call is unnecessary.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # fn do_stuff(x: &[i32]) {}
     /// let x: &[i32] = &[1, 2, 3, 4, 5];
@@ -1159,15 +1175,15 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for using `fold` when a more succinct alternative exists.
+    /// ### What it does
+    /// Checks for using `fold` when a more succinct alternative exists.
     /// Specifically, this checks for `fold`s which could be replaced by `any`, `all`,
     /// `sum` or `product`.
     ///
-    /// **Why is this bad?** Readability.
-    ///
-    /// **Known problems:** None.
+    /// ### Why is this bad?
+    /// Readability.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// let _ = (0..3).fold(false, |acc, x| acc || x > 2);
     /// ```
@@ -1181,16 +1197,16 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for `filter_map` calls which could be replaced by `filter` or `map`.
+    /// ### What it does
+    /// Checks for `filter_map` calls which could be replaced by `filter` or `map`.
     /// More specifically it checks if the closure provided is only performing one of the
     /// filter or map operations and suggests the appropriate option.
     ///
-    /// **Why is this bad?** Complexity. The intent is also clearer if only a single
+    /// ### Why is this bad?
+    /// Complexity. The intent is also clearer if only a single
     /// operation is being performed.
     ///
-    /// **Known problems:** None
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// let _ = (0..3).filter_map(|x| if x > 2 { Some(x) } else { None });
     ///
@@ -1210,17 +1226,16 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for `into_iter` calls on references which should be replaced by `iter`
+    /// ### What it does
+    /// Checks for `into_iter` calls on references which should be replaced by `iter`
     /// or `iter_mut`.
     ///
-    /// **Why is this bad?** Readability. Calling `into_iter` on a reference will not move out its
+    /// ### Why is this bad?
+    /// Readability. Calling `into_iter` on a reference will not move out its
     /// content into the resulting iterator, which is confusing. It is better just call `iter` or
     /// `iter_mut` directly.
     ///
-    /// **Known problems:** None
-    ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust
     /// // Bad
     /// let _ = (&vec![3, 4, 5]).into_iter();
@@ -1234,16 +1249,15 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for calls to `map` followed by a `count`.
+    /// ### What it does
+    /// Checks for calls to `map` followed by a `count`.
     ///
-    /// **Why is this bad?** It looks suspicious. Maybe `map` was confused with `filter`.
+    /// ### Why is this bad?
+    /// It looks suspicious. Maybe `map` was confused with `filter`.
     /// If the `map` call is intentional, this should be rewritten. Or, if you intend to
     /// drive the iterator to completion, you can just use `for_each` instead.
     ///
-    /// **Known problems:** None
-    ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust
     /// let _ = (0..3).map(|x| x + 2).count();
     /// ```
@@ -1253,16 +1267,18 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for `MaybeUninit::uninit().assume_init()`.
+    /// ### What it does
+    /// Checks for `MaybeUninit::uninit().assume_init()`.
     ///
-    /// **Why is this bad?** For most types, this is undefined behavior.
+    /// ### Why is this bad?
+    /// For most types, this is undefined behavior.
     ///
-    /// **Known problems:** For now, we accept empty tuples and tuples / arrays
+    /// ### Known problems
+    /// For now, we accept empty tuples and tuples / arrays
     /// of `MaybeUninit`. There may be other types that allow uninitialized
     /// data, but those are not yet rigorously defined.
     ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust
     /// // Beware the UB
     /// use std::mem::MaybeUninit;
@@ -1285,12 +1301,13 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for `.checked_add/sub(x).unwrap_or(MAX/MIN)`.
+    /// ### What it does
+    /// Checks for `.checked_add/sub(x).unwrap_or(MAX/MIN)`.
     ///
-    /// **Why is this bad?** These can be written simply with `saturating_add/sub` methods.
-    ///
-    /// **Example:**
+    /// ### Why is this bad?
+    /// These can be written simply with `saturating_add/sub` methods.
     ///
+    /// ### Example
     /// ```rust
     /// # let y: u32 = 0;
     /// # let x: u32 = 100;
@@ -1312,14 +1329,14 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for `offset(_)`, `wrapping_`{`add`, `sub`}, etc. on raw pointers to
+    /// ### What it does
+    /// Checks for `offset(_)`, `wrapping_`{`add`, `sub`}, etc. on raw pointers to
     /// zero-sized types
     ///
-    /// **Why is this bad?** This is a no-op, and likely unintended
-    ///
-    /// **Known problems:** None
+    /// ### Why is this bad?
+    /// This is a no-op, and likely unintended
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// unsafe { (&() as *const ()).offset(1) };
     /// ```
@@ -1329,15 +1346,16 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for `FileType::is_file()`.
+    /// ### What it does
+    /// Checks for `FileType::is_file()`.
     ///
-    /// **Why is this bad?** When people testing a file type with `FileType::is_file`
+    /// ### Why is this bad?
+    /// When people testing a file type with `FileType::is_file`
     /// they are testing whether a path is something they can get bytes from. But
     /// `is_file` doesn't cover special file types in unix-like systems, and doesn't cover
     /// symlink in windows. Using `!FileType::is_dir()` is a better way to that intention.
     ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust
     /// # || {
     /// let metadata = std::fs::metadata("foo.txt")?;
@@ -1369,14 +1387,14 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for usage of `_.as_ref().map(Deref::deref)` or it's aliases (such as String::as_str).
+    /// ### What it does
+    /// Checks for usage of `_.as_ref().map(Deref::deref)` or it's aliases (such as String::as_str).
     ///
-    /// **Why is this bad?** Readability, this can be written more concisely as
+    /// ### Why is this bad?
+    /// Readability, this can be written more concisely as
     /// `_.as_deref()`.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # let opt = Some("".to_string());
     /// opt.as_ref().map(String::as_str)
@@ -1394,13 +1412,13 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for usage of `iter().next()` on a Slice or an Array
-    ///
-    /// **Why is this bad?** These can be shortened into `.get()`
+    /// ### What it does
+    /// Checks for usage of `iter().next()` on a Slice or an Array
     ///
-    /// **Known problems:** None.
+    /// ### Why is this bad?
+    /// These can be shortened into `.get()`
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # let a = [1, 2, 3];
     /// # let b = vec![1, 2, 3];
@@ -1420,14 +1438,14 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Warns when using `push_str`/`insert_str` with a single-character string literal
+    /// ### What it does
+    /// Warns when using `push_str`/`insert_str` with a single-character string literal
     /// where `push`/`insert` with a `char` would work fine.
     ///
-    /// **Why is this bad?** It's less clear that we are pushing a single character.
+    /// ### Why is this bad?
+    /// It's less clear that we are pushing a single character.
     ///
-    /// **Known problems:** None
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// let mut string = String::new();
     /// string.insert_str(0, "R");
@@ -1445,7 +1463,8 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** As the counterpart to `or_fun_call`, this lint looks for unnecessary
+    /// ### What it does
+    /// As the counterpart to `or_fun_call`, this lint looks for unnecessary
     /// lazily evaluated closures on `Option` and `Result`.
     ///
     /// This lint suggests changing the following functions, when eager evaluation results in
@@ -1456,13 +1475,14 @@ declare_clippy_lint! {
     ///  - `get_or_insert_with` to `get_or_insert`
     ///  - `ok_or_else` to `ok_or`
     ///
-    /// **Why is this bad?** Using eager evaluation is shorter and simpler in some cases.
+    /// ### Why is this bad?
+    /// Using eager evaluation is shorter and simpler in some cases.
     ///
-    /// **Known problems:** It is possible, but not recommended for `Deref` and `Index` to have
+    /// ### Known problems
+    /// It is possible, but not recommended for `Deref` and `Index` to have
     /// side effects. Eagerly evaluating them can change the semantics of the program.
     ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust
     /// // example code where clippy issues a warning
     /// let opt: Option<u32> = None;
@@ -1481,14 +1501,13 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for usage of `_.map(_).collect::<Result<(), _>()`.
-    ///
-    /// **Why is this bad?** Using `try_for_each` instead is more readable and idiomatic.
-    ///
-    /// **Known problems:** None
+    /// ### What it does
+    /// Checks for usage of `_.map(_).collect::<Result<(), _>()`.
     ///
-    /// **Example:**
+    /// ### Why is this bad?
+    /// Using `try_for_each` instead is more readable and idiomatic.
     ///
+    /// ### Example
     /// ```rust
     /// (0..3).map(|t| Err(t)).collect::<Result<(), _>>();
     /// ```
@@ -1502,16 +1521,15 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for `from_iter()` function calls on types that implement the `FromIterator`
+    /// ### What it does
+    /// Checks for `from_iter()` function calls on types that implement the `FromIterator`
     /// trait.
     ///
-    /// **Why is this bad?** It is recommended style to use collect. See
+    /// ### Why is this bad?
+    /// It is recommended style to use collect. See
     /// [FromIterator documentation](https://doc.rust-lang.org/std/iter/trait.FromIterator.html)
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust
     /// use std::iter::FromIterator;
     ///
@@ -1535,15 +1553,14 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for usage of `inspect().for_each()`.
+    /// ### What it does
+    /// Checks for usage of `inspect().for_each()`.
     ///
-    /// **Why is this bad?** It is the same as performing the computation
+    /// ### Why is this bad?
+    /// It is the same as performing the computation
     /// inside `inspect` at the beginning of the closure in `for_each`.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust
     /// [1,2,3,4,5].iter()
     /// .inspect(|&x| println!("inspect the number: {}", x))
@@ -1565,14 +1582,13 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for usage of `filter_map(|x| x)`.
-    ///
-    /// **Why is this bad?** Readability, this can be written more concisely by using `flatten`.
+    /// ### What it does
+    /// Checks for usage of `filter_map(|x| x)`.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Why is this bad?
+    /// Readability, this can be written more concisely by using `flatten`.
     ///
+    /// ### Example
     /// ```rust
     /// # let iter = vec![Some(1)].into_iter();
     /// iter.filter_map(|x| x);
@@ -1588,14 +1604,13 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for instances of `map(f)` where `f` is the identity function.
-    ///
-    /// **Why is this bad?** It can be written more concisely without the call to `map`.
+    /// ### What it does
+    /// Checks for instances of `map(f)` where `f` is the identity function.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Why is this bad?
+    /// It can be written more concisely without the call to `map`.
     ///
+    /// ### Example
     /// ```rust
     /// let x = [1, 2, 3];
     /// let y: Vec<_> = x.iter().map(|x| x).map(|x| 2*x).collect();
@@ -1611,15 +1626,14 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for the use of `.bytes().nth()`.
+    /// ### What it does
+    /// Checks for the use of `.bytes().nth()`.
     ///
-    /// **Why is this bad?** `.as_bytes().get()` is more efficient and more
+    /// ### Why is this bad?
+    /// `.as_bytes().get()` is more efficient and more
     /// readable.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust
     /// // Bad
     /// let _ = "Hello".bytes().nth(3);
@@ -1633,15 +1647,14 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for the usage of `_.to_owned()`, `vec.to_vec()`, or similar when calling `_.clone()` would be clearer.
+    /// ### What it does
+    /// Checks for the usage of `_.to_owned()`, `vec.to_vec()`, or similar when calling `_.clone()` would be clearer.
     ///
-    /// **Why is this bad?** These methods do the same thing as `_.clone()` but may be confusing as
+    /// ### Why is this bad?
+    /// These methods do the same thing as `_.clone()` but may be confusing as
     /// to why we are calling `to_vec` on something that is already a `Vec` or calling `to_owned` on something that is already owned.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust
     /// let a = vec![1, 2, 3];
     /// let b = a.to_vec();
@@ -1659,15 +1672,14 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for the use of `.iter().count()`.
+    /// ### What it does
+    /// Checks for the use of `.iter().count()`.
     ///
-    /// **Why is this bad?** `.len()` is more efficient and more
+    /// ### Why is this bad?
+    /// `.len()` is more efficient and more
     /// readable.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust
     /// // Bad
     /// let some_vec = vec![0, 1, 2, 3];
@@ -1685,17 +1697,16 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for calls to [`splitn`]
+    /// ### What it does
+    /// Checks for calls to [`splitn`]
     /// (https://doc.rust-lang.org/std/primitive.str.html#method.splitn) and
     /// related functions with either zero or one splits.
     ///
-    /// **Why is this bad?** These calls don't actually split the value and are
+    /// ### Why is this bad?
+    /// These calls don't actually split the value and are
     /// likely to be intended as a different number.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust
     /// // Bad
     /// let s = "";
@@ -1715,14 +1726,13 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for manual implementations of `str::repeat`
-    ///
-    /// **Why is this bad?** These are both harder to read, as well as less performant.
-    ///
-    /// **Known problems:** None.
+    /// ### What it does
+    /// Checks for manual implementations of `str::repeat`
     ///
-    /// **Example:**
+    /// ### Why is this bad?
+    /// These are both harder to read, as well as less performant.
     ///
+    /// ### Example
     /// ```rust
     /// // Bad
     /// let x: String = std::iter::repeat('x').take(10).collect();
diff --git a/clippy_lints/src/minmax.rs b/clippy_lints/src/minmax.rs
index ff3473b744e47..dc2dd45e4edb6 100644
--- a/clippy_lints/src/minmax.rs
+++ b/clippy_lints/src/minmax.rs
@@ -8,15 +8,15 @@ use rustc_session::{declare_lint_pass, declare_tool_lint};
 use std::cmp::Ordering;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for expressions where `std::cmp::min` and `max` are
+    /// ### What it does
+    /// Checks for expressions where `std::cmp::min` and `max` are
     /// used to clamp values, but switched so that the result is constant.
     ///
-    /// **Why is this bad?** This is in all probability not the intended outcome. At
+    /// ### Why is this bad?
+    /// This is in all probability not the intended outcome. At
     /// the least it hurts readability of the code.
     ///
-    /// **Known problems:** None
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```ignore
     /// min(0, max(100, x))
     /// ```
diff --git a/clippy_lints/src/misc.rs b/clippy_lints/src/misc.rs
index 7cfce2e61cca5..c796abe9815a4 100644
--- a/clippy_lints/src/misc.rs
+++ b/clippy_lints/src/misc.rs
@@ -25,10 +25,12 @@ use clippy_utils::{
 };
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for function arguments and let bindings denoted as
+    /// ### What it does
+    /// Checks for function arguments and let bindings denoted as
     /// `ref`.
     ///
-    /// **Why is this bad?** The `ref` declaration makes the function take an owned
+    /// ### Why is this bad?
+    /// The `ref` declaration makes the function take an owned
     /// value, but turns the argument into a reference (which means that the value
     /// is destroyed when exiting the function). This adds not much value: either
     /// take a reference type, or take an owned value and create references in the
@@ -37,11 +39,12 @@ declare_clippy_lint! {
     /// For let bindings, `let x = &foo;` is preferred over `let ref x = foo`. The
     /// type of `x` is more obvious with the former.
     ///
-    /// **Known problems:** If the argument is dereferenced within the function,
+    /// ### Known problems
+    /// If the argument is dereferenced within the function,
     /// removing the `ref` will lead to errors. This can be fixed by removing the
     /// dereferences, e.g., changing `*x` to `x` within the function.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust,ignore
     /// // Bad
     /// fn foo(ref x: u8) -> bool {
@@ -59,14 +62,14 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for comparisons to NaN.
+    /// ### What it does
+    /// Checks for comparisons to NaN.
     ///
-    /// **Why is this bad?** NaN does not compare meaningfully to anything – not
+    /// ### Why is this bad?
+    /// NaN does not compare meaningfully to anything – not
     /// even itself – so those comparisons are simply wrong.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # let x = 1.0;
     ///
@@ -82,18 +85,18 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for (in-)equality comparisons on floating-point
+    /// ### What it does
+    /// Checks for (in-)equality comparisons on floating-point
     /// values (apart from zero), except in functions called `*eq*` (which probably
     /// implement equality for a type involving floats).
     ///
-    /// **Why is this bad?** Floating point calculations are usually imprecise, so
+    /// ### Why is this bad?
+    /// Floating point calculations are usually imprecise, so
     /// asking if two values are *exactly* equal is asking for trouble. For a good
     /// guide on what to do, see [the floating point
     /// guide](http://www.floating-point-gui.de/errors/comparison).
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// let x = 1.2331f64;
     /// let y = 1.2332f64;
@@ -115,16 +118,16 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for conversions to owned values just for the sake
+    /// ### What it does
+    /// Checks for conversions to owned values just for the sake
     /// of a comparison.
     ///
-    /// **Why is this bad?** The comparison can operate on a reference, so creating
+    /// ### Why is this bad?
+    /// The comparison can operate on a reference, so creating
     /// an owned value effectively throws it away directly afterwards, which is
     /// needlessly consuming code and heap space.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # let x = "foo";
     /// # let y = String::from("foo");
@@ -142,18 +145,18 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for getting the remainder of a division by one or minus
+    /// ### What it does
+    /// Checks for getting the remainder of a division by one or minus
     /// one.
     ///
-    /// **Why is this bad?** The result for a divisor of one can only ever be zero; for
+    /// ### Why is this bad?
+    /// The result for a divisor of one can only ever be zero; for
     /// minus one it can cause panic/overflow (if the left operand is the minimal value of
     /// the respective integer type) or results in zero. No one will write such code
     /// deliberately, unless trying to win an Underhanded Rust Contest. Even for that
     /// contest, it's probably a bad idea. Use something more underhanded.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # let x = 1;
     /// let a = x % 1;
@@ -165,17 +168,20 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for the use of bindings with a single leading
+    /// ### What it does
+    /// Checks for the use of bindings with a single leading
     /// underscore.
     ///
-    /// **Why is this bad?** A single leading underscore is usually used to indicate
+    /// ### Why is this bad?
+    /// A single leading underscore is usually used to indicate
     /// that a binding will not be used. Using such a binding breaks this
     /// expectation.
     ///
-    /// **Known problems:** The lint does not work properly with desugaring and
+    /// ### Known problems
+    /// The lint does not work properly with desugaring and
     /// macro, it has been allowed in the mean time.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// let _x = 0;
     /// let y = _x + 1; // Here we are using `_x`, even though it has a leading
@@ -187,17 +193,17 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for the use of short circuit boolean conditions as
+    /// ### What it does
+    /// Checks for the use of short circuit boolean conditions as
     /// a
     /// statement.
     ///
-    /// **Why is this bad?** Using a short circuit boolean condition as a statement
+    /// ### Why is this bad?
+    /// Using a short circuit boolean condition as a statement
     /// may hide the fact that the second part is executed or not depending on the
     /// outcome of the first part.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust,ignore
     /// f() && g(); // We should write `if f() { g(); }`.
     /// ```
@@ -207,15 +213,14 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Catch casts from `0` to some pointer type
+    /// ### What it does
+    /// Catch casts from `0` to some pointer type
     ///
-    /// **Why is this bad?** This generally means `null` and is better expressed as
+    /// ### Why is this bad?
+    /// This generally means `null` and is better expressed as
     /// {`std`, `core`}`::ptr::`{`null`, `null_mut`}.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust
     /// // Bad
     /// let a = 0 as *const u32;
@@ -229,18 +234,18 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for (in-)equality comparisons on floating-point
+    /// ### What it does
+    /// Checks for (in-)equality comparisons on floating-point
     /// value and constant, except in functions called `*eq*` (which probably
     /// implement equality for a type involving floats).
     ///
-    /// **Why is this bad?** Floating point calculations are usually imprecise, so
+    /// ### Why is this bad?
+    /// Floating point calculations are usually imprecise, so
     /// asking if two values are *exactly* equal is asking for trouble. For a good
     /// guide on what to do, see [the floating point
     /// guide](http://www.floating-point-gui.de/errors/comparison).
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// let x: f64 = 1.0;
     /// const ONE: f64 = 1.00;
diff --git a/clippy_lints/src/misc_early/mod.rs b/clippy_lints/src/misc_early/mod.rs
index 050b6805b7c98..06fe967dafc40 100644
--- a/clippy_lints/src/misc_early/mod.rs
+++ b/clippy_lints/src/misc_early/mod.rs
@@ -18,14 +18,14 @@ use rustc_session::{declare_lint_pass, declare_tool_lint};
 use rustc_span::source_map::Span;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for structure field patterns bound to wildcards.
+    /// ### What it does
+    /// Checks for structure field patterns bound to wildcards.
     ///
-    /// **Why is this bad?** Using `..` instead is shorter and leaves the focus on
+    /// ### Why is this bad?
+    /// Using `..` instead is shorter and leaves the focus on
     /// the fields that are actually bound.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # struct Foo {
     /// #     a: i32,
@@ -52,14 +52,14 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for function arguments having the similar names
+    /// ### What it does
+    /// Checks for function arguments having the similar names
     /// differing by an underscore.
     ///
-    /// **Why is this bad?** It affects code readability.
-    ///
-    /// **Known problems:** None.
+    /// ### Why is this bad?
+    /// It affects code readability.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// // Bad
     /// fn foo(a: i32, _a: i32) {}
@@ -73,14 +73,14 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Detects expressions of the form `--x`.
+    /// ### What it does
+    /// Detects expressions of the form `--x`.
     ///
-    /// **Why is this bad?** It can mislead C/C++ programmers to think `x` was
+    /// ### Why is this bad?
+    /// It can mislead C/C++ programmers to think `x` was
     /// decremented.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// let mut x = 3;
     /// --x;
@@ -91,14 +91,14 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Warns on hexadecimal literals with mixed-case letter
+    /// ### What it does
+    /// Warns on hexadecimal literals with mixed-case letter
     /// digits.
     ///
-    /// **Why is this bad?** It looks confusing.
+    /// ### Why is this bad?
+    /// It looks confusing.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// // Bad
     /// let y = 0x1a9BAcD;
@@ -112,14 +112,14 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Warns if literal suffixes are not separated by an
+    /// ### What it does
+    /// Warns if literal suffixes are not separated by an
     /// underscore.
     ///
-    /// **Why is this bad?** It is much less readable.
-    ///
-    /// **Known problems:** None.
+    /// ### Why is this bad?
+    /// It is much less readable.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// // Bad
     /// let y = 123832i32;
@@ -133,17 +133,17 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Warns if an integral constant literal starts with `0`.
+    /// ### What it does
+    /// Warns if an integral constant literal starts with `0`.
     ///
-    /// **Why is this bad?** In some languages (including the infamous C language
+    /// ### Why is this bad?
+    /// In some languages (including the infamous C language
     /// and most of its
     /// family), this marks an octal constant. In Rust however, this is a decimal
     /// constant. This could
     /// be confusing for both the writer and a reader of the constant.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     ///
     /// In Rust:
     /// ```rust
@@ -171,13 +171,13 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Warns if a generic shadows a built-in type.
-    ///
-    /// **Why is this bad?** This gives surprising type errors.
+    /// ### What it does
+    /// Warns if a generic shadows a built-in type.
     ///
-    /// **Known problems:** None.
+    /// ### Why is this bad?
+    /// This gives surprising type errors.
     ///
-    /// **Example:**
+    /// ### Example
     ///
     /// ```ignore
     /// impl<u32> Foo<u32> {
@@ -192,14 +192,14 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for patterns in the form `name @ _`.
+    /// ### What it does
+    /// Checks for patterns in the form `name @ _`.
     ///
-    /// **Why is this bad?** It's almost always more readable to just use direct
+    /// ### Why is this bad?
+    /// It's almost always more readable to just use direct
     /// bindings.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # let v = Some("abc");
     ///
@@ -221,19 +221,19 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for tuple patterns with a wildcard
+    /// ### What it does
+    /// Checks for tuple patterns with a wildcard
     /// pattern (`_`) is next to a rest pattern (`..`).
     ///
     /// _NOTE_: While `_, ..` means there is at least one element left, `..`
     /// means there are 0 or more elements left. This can make a difference
     /// when refactoring, but shouldn't result in errors in the refactored code,
     /// since the wildcard pattern isn't used anyway.
-    /// **Why is this bad?** The wildcard pattern is unneeded as the rest pattern
+    /// ### Why is this bad?
+    /// The wildcard pattern is unneeded as the rest pattern
     /// can match that element as well.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # struct TupleStruct(u32, u32, u32);
     /// # let t = TupleStruct(1, 2, 3);
diff --git a/clippy_lints/src/missing_const_for_fn.rs b/clippy_lints/src/missing_const_for_fn.rs
index 59cbc481ed42e..5b2584d43a130 100644
--- a/clippy_lints/src/missing_const_for_fn.rs
+++ b/clippy_lints/src/missing_const_for_fn.rs
@@ -13,16 +13,13 @@ use rustc_span::Span;
 use rustc_typeck::hir_ty_to_ty;
 
 declare_clippy_lint! {
-    /// **What it does:**
-    ///
+    /// ### What it does
     /// Suggests the use of `const` in functions and methods where possible.
     ///
-    /// **Why is this bad?**
-    ///
+    /// ### Why is this bad?
     /// Not having the function const prevents callers of the function from being const as well.
     ///
-    /// **Known problems:**
-    ///
+    /// ### Known problems
     /// Const functions are currently still being worked on, with some features only being available
     /// on nightly. This lint does not consider all edge cases currently and the suggestions may be
     /// incorrect if you are using this lint on stable.
@@ -42,8 +39,7 @@ declare_clippy_lint! {
     /// can't be const as it calls a non-const function. Making `a` const and running Clippy again,
     /// will suggest to make `b` const, too.
     ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust
     /// # struct Foo {
     /// #     random_number: usize,
diff --git a/clippy_lints/src/missing_doc.rs b/clippy_lints/src/missing_doc.rs
index ec1572c26c262..aeed826890293 100644
--- a/clippy_lints/src/missing_doc.rs
+++ b/clippy_lints/src/missing_doc.rs
@@ -17,15 +17,15 @@ use rustc_span::source_map::Span;
 use rustc_span::sym;
 
 declare_clippy_lint! {
-    /// **What it does:** Warns if there is missing doc for any documentable item
+    /// ### What it does
+    /// Warns if there is missing doc for any documentable item
     /// (public or private).
     ///
-    /// **Why is this bad?** Doc is good. *rustc* has a `MISSING_DOCS`
+    /// ### Why is this bad?
+    /// Doc is good. *rustc* has a `MISSING_DOCS`
     /// allowed-by-default lint for
     /// public members, but has no way to enforce documentation of private items.
     /// This lint fixes that.
-    ///
-    /// **Known problems:** None.
     pub MISSING_DOCS_IN_PRIVATE_ITEMS,
     restriction,
     "detects missing documentation for public and private members"
diff --git a/clippy_lints/src/missing_enforced_import_rename.rs b/clippy_lints/src/missing_enforced_import_rename.rs
index 59565350f7296..9d27870321cac 100644
--- a/clippy_lints/src/missing_enforced_import_rename.rs
+++ b/clippy_lints/src/missing_enforced_import_rename.rs
@@ -10,17 +10,16 @@ use rustc_span::Symbol;
 use crate::utils::conf::Rename;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for imports that do not rename the item as specified
+    /// ### What it does
+    /// Checks for imports that do not rename the item as specified
     /// in the `enforce-import-renames` config option.
     ///
-    /// **Why is this bad?** Consistency is important, if a project has defined import
+    /// ### Why is this bad?
+    /// Consistency is important, if a project has defined import
     /// renames they should be followed. More practically, some item names are too
     /// vague outside of their defining scope this can enforce a more meaningful naming.
     ///
-    /// **Known problems:** None
-    ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// An example clippy.toml configuration:
     /// ```toml
     /// # clippy.toml
diff --git a/clippy_lints/src/missing_inline.rs b/clippy_lints/src/missing_inline.rs
index 041fe64a1a978..be5b4b4006ffd 100644
--- a/clippy_lints/src/missing_inline.rs
+++ b/clippy_lints/src/missing_inline.rs
@@ -7,10 +7,12 @@ use rustc_span::source_map::Span;
 use rustc_span::sym;
 
 declare_clippy_lint! {
-    /// **What it does:** it lints if an exported function, method, trait method with default impl,
+    /// ### What it does
+    /// it lints if an exported function, method, trait method with default impl,
     /// or trait method impl is not `#[inline]`.
     ///
-    /// **Why is this bad?** In general, it is not. Functions can be inlined across
+    /// ### Why is this bad?
+    /// In general, it is not. Functions can be inlined across
     /// crates when that's profitable as long as any form of LTO is used. When LTO is disabled,
     /// functions that are not `#[inline]` cannot be inlined across crates. Certain types of crates
     /// might intend for most of the methods in their public API to be able to be inlined across
@@ -18,9 +20,7 @@ declare_clippy_lint! {
     /// sense. It allows the crate to require all exported methods to be `#[inline]` by default, and
     /// then opt out for specific methods where this might not make sense.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// pub fn foo() {} // missing #[inline]
     /// fn ok() {} // ok
diff --git a/clippy_lints/src/modulo_arithmetic.rs b/clippy_lints/src/modulo_arithmetic.rs
index 1414fdc1b114d..2d14943b56c95 100644
--- a/clippy_lints/src/modulo_arithmetic.rs
+++ b/clippy_lints/src/modulo_arithmetic.rs
@@ -9,18 +9,18 @@ use rustc_session::{declare_lint_pass, declare_tool_lint};
 use std::fmt::Display;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for modulo arithmetic.
+    /// ### What it does
+    /// Checks for modulo arithmetic.
     ///
-    /// **Why is this bad?** The results of modulo (%) operation might differ
+    /// ### Why is this bad?
+    /// The results of modulo (%) operation might differ
     /// depending on the language, when negative numbers are involved.
     /// If you interop with different languages it might be beneficial
     /// to double check all places that use modulo arithmetic.
     ///
     /// For example, in Rust `17 % -3 = 2`, but in Python `17 % -3 = -1`.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// let x = -17 % 3;
     /// ```
diff --git a/clippy_lints/src/multiple_crate_versions.rs b/clippy_lints/src/multiple_crate_versions.rs
index f5ce3e325512d..1c61970fdc8bb 100644
--- a/clippy_lints/src/multiple_crate_versions.rs
+++ b/clippy_lints/src/multiple_crate_versions.rs
@@ -13,17 +13,20 @@ use if_chain::if_chain;
 use itertools::Itertools;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks to see if multiple versions of a crate are being
+    /// ### What it does
+    /// Checks to see if multiple versions of a crate are being
     /// used.
     ///
-    /// **Why is this bad?** This bloats the size of targets, and can lead to
+    /// ### Why is this bad?
+    /// This bloats the size of targets, and can lead to
     /// confusing error messages when structs or traits are used interchangeably
     /// between different versions of a crate.
     ///
-    /// **Known problems:** Because this can be caused purely by the dependencies
+    /// ### Known problems
+    /// Because this can be caused purely by the dependencies
     /// themselves, it's not always possible to fix this issue.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```toml
     /// # This will pull in both winapi v0.3.x and v0.2.x, triggering a warning.
     /// [dependencies]
diff --git a/clippy_lints/src/mut_key.rs b/clippy_lints/src/mut_key.rs
index 68f7cdf6ea0b3..2c7681c45a462 100644
--- a/clippy_lints/src/mut_key.rs
+++ b/clippy_lints/src/mut_key.rs
@@ -10,18 +10,21 @@ use rustc_span::symbol::sym;
 use std::iter;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for sets/maps with mutable key types.
+    /// ### What it does
+    /// Checks for sets/maps with mutable key types.
     ///
-    /// **Why is this bad?** All of `HashMap`, `HashSet`, `BTreeMap` and
+    /// ### Why is this bad?
+    /// All of `HashMap`, `HashSet`, `BTreeMap` and
     /// `BtreeSet` rely on either the hash or the order of keys be unchanging,
     /// so having types with interior mutability is a bad idea.
     ///
-    /// **Known problems:** It's correct to use a struct, that contains interior mutability
+    /// ### Known problems
+    /// It's correct to use a struct, that contains interior mutability
     /// as a key, when its `Hash` implementation doesn't access any of the interior mutable types.
     /// However, this lint is unable to recognize this, so it causes a false positive in theses cases.
     /// The `bytes` crate is a great example of this.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// use std::cmp::{PartialEq, Eq};
     /// use std::collections::HashSet;
diff --git a/clippy_lints/src/mut_mut.rs b/clippy_lints/src/mut_mut.rs
index 4b9c51d0c16cc..d5032c5ba7f29 100644
--- a/clippy_lints/src/mut_mut.rs
+++ b/clippy_lints/src/mut_mut.rs
@@ -9,15 +9,15 @@ use rustc_middle::ty;
 use rustc_session::{declare_lint_pass, declare_tool_lint};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for instances of `mut mut` references.
+    /// ### What it does
+    /// Checks for instances of `mut mut` references.
     ///
-    /// **Why is this bad?** Multiple `mut`s don't add anything meaningful to the
+    /// ### Why is this bad?
+    /// Multiple `mut`s don't add anything meaningful to the
     /// source. This is either a copy'n'paste error, or it shows a fundamental
     /// misunderstanding of references.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # let mut y = 1;
     /// let x = &mut &mut y;
diff --git a/clippy_lints/src/mut_mutex_lock.rs b/clippy_lints/src/mut_mutex_lock.rs
index b9ba74c7d0252..85e870632a5ca 100644
--- a/clippy_lints/src/mut_mutex_lock.rs
+++ b/clippy_lints/src/mut_mutex_lock.rs
@@ -8,17 +8,16 @@ use rustc_middle::ty;
 use rustc_session::{declare_lint_pass, declare_tool_lint};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for `&mut Mutex::lock` calls
+    /// ### What it does
+    /// Checks for `&mut Mutex::lock` calls
     ///
-    /// **Why is this bad?** `Mutex::lock` is less efficient than
+    /// ### Why is this bad?
+    /// `Mutex::lock` is less efficient than
     /// calling `Mutex::get_mut`. In addition you also have a statically
     /// guarantee that the mutex isn't locked, instead of just a runtime
     /// guarantee.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust
     /// use std::sync::{Arc, Mutex};
     ///
diff --git a/clippy_lints/src/mut_reference.rs b/clippy_lints/src/mut_reference.rs
index 6efe8ffcde036..8d5d7951fc532 100644
--- a/clippy_lints/src/mut_reference.rs
+++ b/clippy_lints/src/mut_reference.rs
@@ -7,15 +7,15 @@ use rustc_session::{declare_lint_pass, declare_tool_lint};
 use std::iter;
 
 declare_clippy_lint! {
-    /// **What it does:** Detects passing a mutable reference to a function that only
+    /// ### What it does
+    /// Detects passing a mutable reference to a function that only
     /// requires an immutable reference.
     ///
-    /// **Why is this bad?** The mutable reference rules out all other references to
+    /// ### Why is this bad?
+    /// The mutable reference rules out all other references to
     /// the value. Also the code misleads about the intent of the call site.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```ignore
     /// // Bad
     /// my_vec.push(&mut value)
diff --git a/clippy_lints/src/mutable_debug_assertion.rs b/clippy_lints/src/mutable_debug_assertion.rs
index 81bf853300fe5..ee50891cc3103 100644
--- a/clippy_lints/src/mutable_debug_assertion.rs
+++ b/clippy_lints/src/mutable_debug_assertion.rs
@@ -9,17 +9,17 @@ use rustc_session::{declare_lint_pass, declare_tool_lint};
 use rustc_span::Span;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for function/method calls with a mutable
+    /// ### What it does
+    /// Checks for function/method calls with a mutable
     /// parameter in `debug_assert!`, `debug_assert_eq!` and `debug_assert_ne!` macros.
     ///
-    /// **Why is this bad?** In release builds `debug_assert!` macros are optimized out by the
+    /// ### Why is this bad?
+    /// In release builds `debug_assert!` macros are optimized out by the
     /// compiler.
     /// Therefore mutating something in a `debug_assert!` macro results in different behaviour
     /// between a release and debug build.
     ///
-    /// **Known problems:** None
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust,ignore
     /// debug_assert_eq!(vec![3].pop(), Some(3));
     /// // or
diff --git a/clippy_lints/src/mutex_atomic.rs b/clippy_lints/src/mutex_atomic.rs
index 354e2c3fb7480..436ceec6cfa0b 100644
--- a/clippy_lints/src/mutex_atomic.rs
+++ b/clippy_lints/src/mutex_atomic.rs
@@ -10,17 +10,20 @@ use rustc_middle::ty::{self, Ty};
 use rustc_session::{declare_lint_pass, declare_tool_lint};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for usages of `Mutex<X>` where an atomic will do.
+    /// ### What it does
+    /// Checks for usages of `Mutex<X>` where an atomic will do.
     ///
-    /// **Why is this bad?** Using a mutex just to make access to a plain bool or
+    /// ### Why is this bad?
+    /// Using a mutex just to make access to a plain bool or
     /// reference sequential is shooting flies with cannons.
     /// `std::sync::atomic::AtomicBool` and `std::sync::atomic::AtomicPtr` are leaner and
     /// faster.
     ///
-    /// **Known problems:** This lint cannot detect if the mutex is actually used
+    /// ### Known problems
+    /// This lint cannot detect if the mutex is actually used
     /// for waiting before a critical section.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # let y = true;
     ///
@@ -38,17 +41,20 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for usages of `Mutex<X>` where `X` is an integral
+    /// ### What it does
+    /// Checks for usages of `Mutex<X>` where `X` is an integral
     /// type.
     ///
-    /// **Why is this bad?** Using a mutex just to make access to a plain integer
+    /// ### Why is this bad?
+    /// Using a mutex just to make access to a plain integer
     /// sequential is
     /// shooting flies with cannons. `std::sync::atomic::AtomicUsize` is leaner and faster.
     ///
-    /// **Known problems:** This lint cannot detect if the mutex is actually used
+    /// ### Known problems
+    /// This lint cannot detect if the mutex is actually used
     /// for waiting before a critical section.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # use std::sync::Mutex;
     /// let x = Mutex::new(0usize);
diff --git a/clippy_lints/src/needless_arbitrary_self_type.rs b/clippy_lints/src/needless_arbitrary_self_type.rs
index fe3c4455be5e2..9a3d9383cd98c 100644
--- a/clippy_lints/src/needless_arbitrary_self_type.rs
+++ b/clippy_lints/src/needless_arbitrary_self_type.rs
@@ -9,13 +9,13 @@ use rustc_span::symbol::kw;
 use rustc_span::Span;
 
 declare_clippy_lint! {
-    /// **What it does:** The lint checks for `self` in fn parameters that
+    /// ### What it does
+    /// The lint checks for `self` in fn parameters that
     /// specify the `Self`-type explicitly
-    /// **Why is this bad?** Increases the amount and decreases the readability of code
+    /// ### Why is this bad?
+    /// Increases the amount and decreases the readability of code
     ///
-    /// **Known problems:** None
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// enum ValType {
     ///     I32,
diff --git a/clippy_lints/src/needless_bitwise_bool.rs b/clippy_lints/src/needless_bitwise_bool.rs
index b30bfbd429443..203da29cb9170 100644
--- a/clippy_lints/src/needless_bitwise_bool.rs
+++ b/clippy_lints/src/needless_bitwise_bool.rs
@@ -9,20 +9,19 @@ use rustc_middle::ty;
 use rustc_session::{declare_lint_pass, declare_tool_lint};
 
 declare_clippy_lint! {
-    /// **What it does:**
+    /// ### What it does
     /// Checks for uses of bitwise and/or operators between booleans, where performance may be improved by using
     /// a lazy and.
     ///
-    /// **Why is this bad?**
+    /// ### Why is this bad?
     /// The bitwise operators do not support short-circuiting, so it may hinder code performance.
     /// Additionally, boolean logic "masked" as bitwise logic is not caught by lints like `unnecessary_fold`
     ///
-    /// **Known problems:**
+    /// ### Known problems
     /// This lint evaluates only when the right side is determined to have no side effects. At this time, that
     /// determination is quite conservative.
     ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust
     /// let (x,y) = (true, false);
     /// if x & !y {} // where both x and y are booleans
diff --git a/clippy_lints/src/needless_bool.rs b/clippy_lints/src/needless_bool.rs
index 780690548e52b..36f2829a5b94e 100644
--- a/clippy_lints/src/needless_bool.rs
+++ b/clippy_lints/src/needless_bool.rs
@@ -15,17 +15,20 @@ use rustc_span::source_map::Spanned;
 use rustc_span::Span;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for expressions of the form `if c { true } else {
+    /// ### What it does
+    /// Checks for expressions of the form `if c { true } else {
     /// false }` (or vice versa) and suggests using the condition directly.
     ///
-    /// **Why is this bad?** Redundant code.
+    /// ### Why is this bad?
+    /// Redundant code.
     ///
-    /// **Known problems:** Maybe false positives: Sometimes, the two branches are
+    /// ### Known problems
+    /// Maybe false positives: Sometimes, the two branches are
     /// painstakingly documented (which we, of course, do not detect), so they *may*
     /// have some value. Even then, the documentation can be rewritten to match the
     /// shorter code.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust,ignore
     /// if x {
     ///     false
@@ -43,15 +46,15 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for expressions of the form `x == true`,
+    /// ### What it does
+    /// Checks for expressions of the form `x == true`,
     /// `x != true` and order comparisons such as `x < true` (or vice versa) and
     /// suggest using the variable directly.
     ///
-    /// **Why is this bad?** Unnecessary code.
+    /// ### Why is this bad?
+    /// Unnecessary code.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust,ignore
     /// if x == true {}
     /// if y == false {}
diff --git a/clippy_lints/src/needless_borrow.rs b/clippy_lints/src/needless_borrow.rs
index dd1dfa2bdfbcf..3f0b23ee4d3e4 100644
--- a/clippy_lints/src/needless_borrow.rs
+++ b/clippy_lints/src/needless_borrow.rs
@@ -17,15 +17,15 @@ use rustc_session::{declare_tool_lint, impl_lint_pass};
 use rustc_span::Span;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for address of operations (`&`) that are going to
+    /// ### What it does
+    /// Checks for address of operations (`&`) that are going to
     /// be dereferenced immediately by the compiler.
     ///
-    /// **Why is this bad?** Suggests that the receiver of the expression borrows
+    /// ### Why is this bad?
+    /// Suggests that the receiver of the expression borrows
     /// the expression.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// // Bad
     /// let x: &i32 = &&&&&&5;
@@ -39,13 +39,13 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for `ref` bindings which create a reference to a reference.
-    ///
-    /// **Why is this bad?** The address-of operator at the use site is clearer about the need for a reference.
+    /// ### What it does
+    /// Checks for `ref` bindings which create a reference to a reference.
     ///
-    /// **Known problems:** None.
+    /// ### Why is this bad?
+    /// The address-of operator at the use site is clearer about the need for a reference.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// // Bad
     /// let x = Some("");
diff --git a/clippy_lints/src/needless_borrowed_ref.rs b/clippy_lints/src/needless_borrowed_ref.rs
index 0e976b130ebf1..36879eda7c003 100644
--- a/clippy_lints/src/needless_borrowed_ref.rs
+++ b/clippy_lints/src/needless_borrowed_ref.rs
@@ -7,12 +7,15 @@ use rustc_lint::{LateContext, LateLintPass};
 use rustc_session::{declare_lint_pass, declare_tool_lint};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for bindings that destructure a reference and borrow the inner
+    /// ### What it does
+    /// Checks for bindings that destructure a reference and borrow the inner
     /// value with `&ref`.
     ///
-    /// **Why is this bad?** This pattern has no effect in almost all cases.
+    /// ### Why is this bad?
+    /// This pattern has no effect in almost all cases.
     ///
-    /// **Known problems:** In some cases, `&ref` is needed to avoid a lifetime mismatch error.
+    /// ### Known problems
+    /// In some cases, `&ref` is needed to avoid a lifetime mismatch error.
     /// Example:
     /// ```rust
     /// fn foo(a: &Option<String>, b: &Option<String>) {
@@ -23,7 +26,7 @@ declare_clippy_lint! {
     /// }
     /// ```
     ///
-    /// **Example:**
+    /// ### Example
     /// Bad:
     /// ```rust
     /// let mut v = Vec::<String>::new();
diff --git a/clippy_lints/src/needless_continue.rs b/clippy_lints/src/needless_continue.rs
index 1d19413e0d013..5088b8bb0d368 100644
--- a/clippy_lints/src/needless_continue.rs
+++ b/clippy_lints/src/needless_continue.rs
@@ -42,20 +42,20 @@ use rustc_span::source_map::{original_sp, DUMMY_SP};
 use rustc_span::Span;
 
 declare_clippy_lint! {
-    /// **What it does:** The lint checks for `if`-statements appearing in loops
+    /// ### What it does
+    /// The lint checks for `if`-statements appearing in loops
     /// that contain a `continue` statement in either their main blocks or their
     /// `else`-blocks, when omitting the `else`-block possibly with some
     /// rearrangement of code can make the code easier to understand.
     ///
-    /// **Why is this bad?** Having explicit `else` blocks for `if` statements
+    /// ### Why is this bad?
+    /// Having explicit `else` blocks for `if` statements
     /// containing `continue` in their THEN branch adds unnecessary branching and
     /// nesting to the code. Having an else block containing just `continue` can
     /// also be better written by grouping the statements following the whole `if`
     /// statement within the THEN block and omitting the else block completely.
     ///
-    /// **Known problems:** None
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # fn condition() -> bool { false }
     /// # fn update_condition() {}
diff --git a/clippy_lints/src/needless_for_each.rs b/clippy_lints/src/needless_for_each.rs
index a723a472a25fe..d9aa42fe8eeb6 100644
--- a/clippy_lints/src/needless_for_each.rs
+++ b/clippy_lints/src/needless_for_each.rs
@@ -16,18 +16,17 @@ use clippy_utils::source::snippet_with_applicability;
 use clippy_utils::ty::has_iter_method;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for usage of `for_each` that would be more simply written as a
+    /// ### What it does
+    /// Checks for usage of `for_each` that would be more simply written as a
     /// `for` loop.
     ///
-    /// **Why is this bad?** `for_each` may be used after applying iterator transformers like
+    /// ### Why is this bad?
+    /// `for_each` may be used after applying iterator transformers like
     /// `filter` for better readability and performance. It may also be used to fit a simple
     /// operation on one line.
     /// But when none of these apply, a simple `for` loop is more idiomatic.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust
     /// let v = vec![0, 1, 2];
     /// v.iter().for_each(|elem| {
diff --git a/clippy_lints/src/needless_pass_by_value.rs b/clippy_lints/src/needless_pass_by_value.rs
index 283b1847b6c99..03eeb54d8d1c2 100644
--- a/clippy_lints/src/needless_pass_by_value.rs
+++ b/clippy_lints/src/needless_pass_by_value.rs
@@ -24,20 +24,22 @@ use rustc_typeck::expr_use_visitor as euv;
 use std::borrow::Cow;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for functions taking arguments by value, but not
+    /// ### What it does
+    /// Checks for functions taking arguments by value, but not
     /// consuming them in its
     /// body.
     ///
-    /// **Why is this bad?** Taking arguments by reference is more flexible and can
+    /// ### Why is this bad?
+    /// Taking arguments by reference is more flexible and can
     /// sometimes avoid
     /// unnecessary allocations.
     ///
-    /// **Known problems:**
+    /// ### Known problems
     /// * This lint suggests taking an argument by reference,
     /// however sometimes it is better to let users decide the argument type
     /// (by using `Borrow` trait, for example), depending on how the function is used.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// fn foo(v: Vec<i32>) {
     ///     assert_eq!(v.len(), 42);
diff --git a/clippy_lints/src/needless_question_mark.rs b/clippy_lints/src/needless_question_mark.rs
index c64491c63e2dc..42e48336e1539 100644
--- a/clippy_lints/src/needless_question_mark.rs
+++ b/clippy_lints/src/needless_question_mark.rs
@@ -10,15 +10,13 @@ use rustc_middle::ty::TyS;
 use rustc_session::{declare_lint_pass, declare_tool_lint};
 
 declare_clippy_lint! {
-    /// **What it does:**
+    /// ### What it does
     /// Suggests alternatives for useless applications of `?` in terminating expressions
     ///
-    /// **Why is this bad?** There's no reason to use `?` to short-circuit when execution of the body will end there anyway.
-    ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Why is this bad?
+    /// There's no reason to use `?` to short-circuit when execution of the body will end there anyway.
     ///
+    /// ### Example
     /// ```rust
     /// struct TO {
     ///     magic: Option<usize>,
diff --git a/clippy_lints/src/needless_update.rs b/clippy_lints/src/needless_update.rs
index 8f325404deb45..2a33b7392caa4 100644
--- a/clippy_lints/src/needless_update.rs
+++ b/clippy_lints/src/needless_update.rs
@@ -5,18 +5,18 @@ use rustc_middle::ty;
 use rustc_session::{declare_lint_pass, declare_tool_lint};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for needlessly including a base struct on update
+    /// ### What it does
+    /// Checks for needlessly including a base struct on update
     /// when all fields are changed anyway.
     ///
     /// This lint is not applied to structs marked with
     /// [non_exhaustive](https://doc.rust-lang.org/reference/attributes/type_system.html).
     ///
-    /// **Why is this bad?** This will cost resources (because the base has to be
+    /// ### Why is this bad?
+    /// This will cost resources (because the base has to be
     /// somewhere), and make the code less readable.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # struct Point {
     /// #     x: i32,
diff --git a/clippy_lints/src/neg_cmp_op_on_partial_ord.rs b/clippy_lints/src/neg_cmp_op_on_partial_ord.rs
index c824f6f54b5cc..6ad49b7060565 100644
--- a/clippy_lints/src/neg_cmp_op_on_partial_ord.rs
+++ b/clippy_lints/src/neg_cmp_op_on_partial_ord.rs
@@ -8,19 +8,16 @@ use rustc_middle::lint::in_external_macro;
 use rustc_session::{declare_lint_pass, declare_tool_lint};
 
 declare_clippy_lint! {
-    /// **What it does:**
+    /// ### What it does
     /// Checks for the usage of negated comparison operators on types which only implement
     /// `PartialOrd` (e.g., `f64`).
     ///
-    /// **Why is this bad?**
+    /// ### Why is this bad?
     /// These operators make it easy to forget that the underlying types actually allow not only three
     /// potential Orderings (Less, Equal, Greater) but also a fourth one (Uncomparable). This is
     /// especially easy to miss if the operator based comparison result is negated.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust
     /// use std::cmp::Ordering;
     ///
diff --git a/clippy_lints/src/neg_multiply.rs b/clippy_lints/src/neg_multiply.rs
index d5e1ea6d242de..fa36d8fb1b30f 100644
--- a/clippy_lints/src/neg_multiply.rs
+++ b/clippy_lints/src/neg_multiply.rs
@@ -7,13 +7,16 @@ use rustc_session::{declare_lint_pass, declare_tool_lint};
 use rustc_span::source_map::Span;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for multiplication by -1 as a form of negation.
+    /// ### What it does
+    /// Checks for multiplication by -1 as a form of negation.
     ///
-    /// **Why is this bad?** It's more readable to just negate.
+    /// ### Why is this bad?
+    /// It's more readable to just negate.
     ///
-    /// **Known problems:** This only catches integers (for now).
+    /// ### Known problems
+    /// This only catches integers (for now).
     ///
-    /// **Example:**
+    /// ### Example
     /// ```ignore
     /// x * -1
     /// ```
diff --git a/clippy_lints/src/new_without_default.rs b/clippy_lints/src/new_without_default.rs
index bc409dd6efb4d..5c63d245bf120 100644
--- a/clippy_lints/src/new_without_default.rs
+++ b/clippy_lints/src/new_without_default.rs
@@ -13,18 +13,17 @@ use rustc_session::{declare_tool_lint, impl_lint_pass};
 use rustc_span::sym;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for types with a `fn new() -> Self` method and no
+    /// ### What it does
+    /// Checks for types with a `fn new() -> Self` method and no
     /// implementation of
     /// [`Default`](https://doc.rust-lang.org/std/default/trait.Default.html).
     ///
-    /// **Why is this bad?** The user might expect to be able to use
+    /// ### Why is this bad?
+    /// The user might expect to be able to use
     /// [`Default`](https://doc.rust-lang.org/std/default/trait.Default.html) as the
     /// type can be constructed without arguments.
     ///
-    /// **Known problems:** Hopefully none.
-    ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```ignore
     /// struct Foo(Bar);
     ///
diff --git a/clippy_lints/src/no_effect.rs b/clippy_lints/src/no_effect.rs
index 910b05360925d..e07518b258687 100644
--- a/clippy_lints/src/no_effect.rs
+++ b/clippy_lints/src/no_effect.rs
@@ -9,15 +9,15 @@ use rustc_session::{declare_lint_pass, declare_tool_lint};
 use std::ops::Deref;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for statements which have no effect.
+    /// ### What it does
+    /// Checks for statements which have no effect.
     ///
-    /// **Why is this bad?** Similar to dead code, these statements are actually
+    /// ### Why is this bad?
+    /// Similar to dead code, these statements are actually
     /// executed. However, as they have no effect, all they do is make the code less
     /// readable.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// 0;
     /// ```
@@ -27,15 +27,15 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for expression statements that can be reduced to a
+    /// ### What it does
+    /// Checks for expression statements that can be reduced to a
     /// sub-expression.
     ///
-    /// **Why is this bad?** Expressions by themselves often have no side-effects.
+    /// ### Why is this bad?
+    /// Expressions by themselves often have no side-effects.
     /// Having such expressions reduces readability.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust,ignore
     /// compute_array()[0];
     /// ```
diff --git a/clippy_lints/src/non_copy_const.rs b/clippy_lints/src/non_copy_const.rs
index d775cd7c7f740..aa3067876ebf8 100644
--- a/clippy_lints/src/non_copy_const.rs
+++ b/clippy_lints/src/non_copy_const.rs
@@ -24,10 +24,12 @@ use rustc_typeck::hir_ty_to_ty;
 // FIXME: this is a correctness problem but there's no suitable
 // warn-by-default category.
 declare_clippy_lint! {
-    /// **What it does:** Checks for declaration of `const` items which is interior
+    /// ### What it does
+    /// Checks for declaration of `const` items which is interior
     /// mutable (e.g., contains a `Cell`, `Mutex`, `AtomicXxxx`, etc.).
     ///
-    /// **Why is this bad?** Consts are copied everywhere they are referenced, i.e.,
+    /// ### Why is this bad?
+    /// Consts are copied everywhere they are referenced, i.e.,
     /// every time you refer to the const a fresh instance of the `Cell` or `Mutex`
     /// or `AtomicXxxx` will be created, which defeats the whole purpose of using
     /// these types in the first place.
@@ -35,7 +37,8 @@ declare_clippy_lint! {
     /// The `const` should better be replaced by a `static` item if a global
     /// variable is wanted, or replaced by a `const fn` if a constructor is wanted.
     ///
-    /// **Known problems:** A "non-constant" const item is a legacy way to supply an
+    /// ### Known problems
+    /// A "non-constant" const item is a legacy way to supply an
     /// initialized value to downstream `static` items (e.g., the
     /// `std::sync::ONCE_INIT` constant). In this case the use of `const` is legit,
     /// and this lint should be suppressed.
@@ -52,7 +55,7 @@ declare_clippy_lint! {
     /// the interior mutable field is used or not. See issues
     /// [#5812](https://github.com/rust-lang/rust-clippy/issues/5812) and
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// use std::sync::atomic::{AtomicUsize, Ordering::SeqCst};
     ///
@@ -74,17 +77,20 @@ declare_clippy_lint! {
 // FIXME: this is a correctness problem but there's no suitable
 // warn-by-default category.
 declare_clippy_lint! {
-    /// **What it does:** Checks if `const` items which is interior mutable (e.g.,
+    /// ### What it does
+    /// Checks if `const` items which is interior mutable (e.g.,
     /// contains a `Cell`, `Mutex`, `AtomicXxxx`, etc.) has been borrowed directly.
     ///
-    /// **Why is this bad?** Consts are copied everywhere they are referenced, i.e.,
+    /// ### Why is this bad?
+    /// Consts are copied everywhere they are referenced, i.e.,
     /// every time you refer to the const a fresh instance of the `Cell` or `Mutex`
     /// or `AtomicXxxx` will be created, which defeats the whole purpose of using
     /// these types in the first place.
     ///
     /// The `const` value should be stored inside a `static` item.
     ///
-    /// **Known problems:** When an enum has variants with interior mutability, use of its non
+    /// ### Known problems
+    /// When an enum has variants with interior mutability, use of its non
     /// interior mutable variants can generate false positives. See issue
     /// [#3962](https://github.com/rust-lang/rust-clippy/issues/3962)
     ///
@@ -93,7 +99,7 @@ declare_clippy_lint! {
     /// [#5812](https://github.com/rust-lang/rust-clippy/issues/5812) and
     /// [#3825](https://github.com/rust-lang/rust-clippy/issues/3825)
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// use std::sync::atomic::{AtomicUsize, Ordering::SeqCst};
     /// const CONST_ATOM: AtomicUsize = AtomicUsize::new(12);
diff --git a/clippy_lints/src/non_expressive_names.rs b/clippy_lints/src/non_expressive_names.rs
index 7183a7c3858a8..dc55b103eb6f9 100644
--- a/clippy_lints/src/non_expressive_names.rs
+++ b/clippy_lints/src/non_expressive_names.rs
@@ -12,14 +12,14 @@ use rustc_span::symbol::{Ident, Symbol};
 use std::cmp::Ordering;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for names that are very similar and thus confusing.
+    /// ### What it does
+    /// Checks for names that are very similar and thus confusing.
     ///
-    /// **Why is this bad?** It's hard to distinguish between names that differ only
+    /// ### Why is this bad?
+    /// It's hard to distinguish between names that differ only
     /// by a single character.
     ///
-    /// **Known problems:** None?
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```ignore
     /// let checked_exp = something;
     /// let checked_expr = something_else;
@@ -30,15 +30,15 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for too many variables whose name consists of a
+    /// ### What it does
+    /// Checks for too many variables whose name consists of a
     /// single character.
     ///
-    /// **Why is this bad?** It's hard to memorize what a variable means without a
+    /// ### Why is this bad?
+    /// It's hard to memorize what a variable means without a
     /// descriptive name.
     ///
-    /// **Known problems:** None?
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```ignore
     /// let (a, b, c, d, e, f, g) = (...);
     /// ```
@@ -48,15 +48,15 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks if you have variables whose name consists of just
+    /// ### What it does
+    /// Checks if you have variables whose name consists of just
     /// underscores and digits.
     ///
-    /// **Why is this bad?** It's hard to memorize what a variable means without a
+    /// ### Why is this bad?
+    /// It's hard to memorize what a variable means without a
     /// descriptive name.
     ///
-    /// **Known problems:** None?
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// let _1 = 1;
     /// let ___1 = 1;
diff --git a/clippy_lints/src/non_octal_unix_permissions.rs b/clippy_lints/src/non_octal_unix_permissions.rs
index a83daea97bf6b..3b74f69d3753a 100644
--- a/clippy_lints/src/non_octal_unix_permissions.rs
+++ b/clippy_lints/src/non_octal_unix_permissions.rs
@@ -9,15 +9,14 @@ use rustc_lint::{LateContext, LateLintPass};
 use rustc_session::{declare_lint_pass, declare_tool_lint};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for non-octal values used to set Unix file permissions.
+    /// ### What it does
+    /// Checks for non-octal values used to set Unix file permissions.
     ///
-    /// **Why is this bad?** They will be converted into octal, creating potentially
+    /// ### Why is this bad?
+    /// They will be converted into octal, creating potentially
     /// unintended file permissions.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust,ignore
     /// use std::fs::OpenOptions;
     /// use std::os::unix::fs::OpenOptionsExt;
diff --git a/clippy_lints/src/nonstandard_macro_braces.rs b/clippy_lints/src/nonstandard_macro_braces.rs
index 043e7fa30d6e9..dbe9cbe0ded83 100644
--- a/clippy_lints/src/nonstandard_macro_braces.rs
+++ b/clippy_lints/src/nonstandard_macro_braces.rs
@@ -13,16 +13,14 @@ use rustc_span::Span;
 use serde::{de, Deserialize};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks that common macros are used with consistent bracing.
+    /// ### What it does
+    /// Checks that common macros are used with consistent bracing.
     ///
-    /// **Why is this bad?** This is mostly a consistency lint although using () or []
+    /// ### Why is this bad?
+    /// This is mostly a consistency lint although using () or []
     /// doesn't give you a semicolon in item position, which can be unexpected.
     ///
-    /// **Known problems:**
-    /// None
-    ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust
     /// vec!{1, 2, 3};
     /// ```
diff --git a/clippy_lints/src/open_options.rs b/clippy_lints/src/open_options.rs
index fded48038e39f..4064d94da2abf 100644
--- a/clippy_lints/src/open_options.rs
+++ b/clippy_lints/src/open_options.rs
@@ -8,15 +8,15 @@ use rustc_session::{declare_lint_pass, declare_tool_lint};
 use rustc_span::source_map::{Span, Spanned};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for duplicate open options as well as combinations
+    /// ### What it does
+    /// Checks for duplicate open options as well as combinations
     /// that make no sense.
     ///
-    /// **Why is this bad?** In the best case, the code will be harder to read than
+    /// ### Why is this bad?
+    /// In the best case, the code will be harder to read than
     /// necessary. I don't know the worst case.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// use std::fs::OpenOptions;
     ///
diff --git a/clippy_lints/src/option_env_unwrap.rs b/clippy_lints/src/option_env_unwrap.rs
index b6f518661bdb1..d7306628030f6 100644
--- a/clippy_lints/src/option_env_unwrap.rs
+++ b/clippy_lints/src/option_env_unwrap.rs
@@ -7,17 +7,16 @@ use rustc_session::{declare_lint_pass, declare_tool_lint};
 use rustc_span::sym;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for usage of `option_env!(...).unwrap()` and
+    /// ### What it does
+    /// Checks for usage of `option_env!(...).unwrap()` and
     /// suggests usage of the `env!` macro.
     ///
-    /// **Why is this bad?** Unwrapping the result of `option_env!` will panic
+    /// ### Why is this bad?
+    /// Unwrapping the result of `option_env!` will panic
     /// at run-time if the environment variable doesn't exist, whereas `env!`
     /// catches it at compile-time.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust,no_run
     /// let _ = option_env!("HOME").unwrap();
     /// ```
diff --git a/clippy_lints/src/option_if_let_else.rs b/clippy_lints/src/option_if_let_else.rs
index b2be35bdddb38..7aef3a5f34cf2 100644
--- a/clippy_lints/src/option_if_let_else.rs
+++ b/clippy_lints/src/option_if_let_else.rs
@@ -12,24 +12,23 @@ use rustc_session::{declare_lint_pass, declare_tool_lint};
 use rustc_span::sym;
 
 declare_clippy_lint! {
-    /// **What it does:**
+    /// ### What it does
     /// Lints usage of `if let Some(v) = ... { y } else { x }` which is more
     /// idiomatically done with `Option::map_or` (if the else bit is a pure
     /// expression) or `Option::map_or_else` (if the else bit is an impure
     /// expression).
     ///
-    /// **Why is this bad?**
+    /// ### Why is this bad?
     /// Using the dedicated functions of the Option type is clearer and
     /// more concise than an `if let` expression.
     ///
-    /// **Known problems:**
+    /// ### Known problems
     /// This lint uses a deliberately conservative metric for checking
     /// if the inside of either body contains breaks or continues which will
     /// cause it to not suggest a fix if either block contains a loop with
     /// continues or breaks contained within the loop.
     ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust
     /// # let optional: Option<u32> = Some(0);
     /// # fn do_complicated_function() -> u32 { 5 };
diff --git a/clippy_lints/src/overflow_check_conditional.rs b/clippy_lints/src/overflow_check_conditional.rs
index e222782c2cc8c..34755afdb72f0 100644
--- a/clippy_lints/src/overflow_check_conditional.rs
+++ b/clippy_lints/src/overflow_check_conditional.rs
@@ -6,14 +6,14 @@ use rustc_lint::{LateContext, LateLintPass};
 use rustc_session::{declare_lint_pass, declare_tool_lint};
 
 declare_clippy_lint! {
-    /// **What it does:** Detects classic underflow/overflow checks.
+    /// ### What it does
+    /// Detects classic underflow/overflow checks.
     ///
-    /// **Why is this bad?** Most classic C underflow/overflow checks will fail in
+    /// ### Why is this bad?
+    /// Most classic C underflow/overflow checks will fail in
     /// Rust. Users can use functions like `overflowing_*` and `wrapping_*` instead.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # let a = 1;
     /// # let b = 2;
diff --git a/clippy_lints/src/panic_in_result_fn.rs b/clippy_lints/src/panic_in_result_fn.rs
index cef74d87e7c01..e2b6ba8e2d2f6 100644
--- a/clippy_lints/src/panic_in_result_fn.rs
+++ b/clippy_lints/src/panic_in_result_fn.rs
@@ -8,14 +8,16 @@ use rustc_session::{declare_lint_pass, declare_tool_lint};
 use rustc_span::{sym, Span};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for usage of `panic!`, `unimplemented!`, `todo!`, `unreachable!` or assertions in a function of type result.
+    /// ### What it does
+    /// Checks for usage of `panic!`, `unimplemented!`, `todo!`, `unreachable!` or assertions in a function of type result.
     ///
-    /// **Why is this bad?** For some codebases, it is desirable for functions of type result to return an error instead of crashing. Hence panicking macros should be avoided.
+    /// ### Why is this bad?
+    /// For some codebases, it is desirable for functions of type result to return an error instead of crashing. Hence panicking macros should be avoided.
     ///
-    /// **Known problems:** Functions called from a function returning a `Result` may invoke a panicking macro. This is not checked.
-    ///
-    /// **Example:**
+    /// ### Known problems
+    /// Functions called from a function returning a `Result` may invoke a panicking macro. This is not checked.
     ///
+    /// ### Example
     /// ```rust
     /// fn result_with_panic() -> Result<bool, String>
     /// {
diff --git a/clippy_lints/src/panic_unimplemented.rs b/clippy_lints/src/panic_unimplemented.rs
index dc28874c16e67..d8d9081d6f172 100644
--- a/clippy_lints/src/panic_unimplemented.rs
+++ b/clippy_lints/src/panic_unimplemented.rs
@@ -7,13 +7,13 @@ use rustc_session::{declare_lint_pass, declare_tool_lint};
 use rustc_span::Span;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for usage of `panic!`.
+    /// ### What it does
+    /// Checks for usage of `panic!`.
     ///
-    /// **Why is this bad?** `panic!` will stop the execution of the executable
+    /// ### Why is this bad?
+    /// `panic!` will stop the execution of the executable
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```no_run
     /// panic!("even with a good reason");
     /// ```
@@ -23,13 +23,13 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for usage of `unimplemented!`.
-    ///
-    /// **Why is this bad?** This macro should not be present in production code
+    /// ### What it does
+    /// Checks for usage of `unimplemented!`.
     ///
-    /// **Known problems:** None.
+    /// ### Why is this bad?
+    /// This macro should not be present in production code
     ///
-    /// **Example:**
+    /// ### Example
     /// ```no_run
     /// unimplemented!();
     /// ```
@@ -39,13 +39,13 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for usage of `todo!`.
+    /// ### What it does
+    /// Checks for usage of `todo!`.
     ///
-    /// **Why is this bad?** This macro should not be present in production code
+    /// ### Why is this bad?
+    /// This macro should not be present in production code
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```no_run
     /// todo!();
     /// ```
@@ -55,13 +55,13 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for usage of `unreachable!`.
-    ///
-    /// **Why is this bad?** This macro can cause code to panic
+    /// ### What it does
+    /// Checks for usage of `unreachable!`.
     ///
-    /// **Known problems:** None.
+    /// ### Why is this bad?
+    /// This macro can cause code to panic
     ///
-    /// **Example:**
+    /// ### Example
     /// ```no_run
     /// unreachable!();
     /// ```
diff --git a/clippy_lints/src/partialeq_ne_impl.rs b/clippy_lints/src/partialeq_ne_impl.rs
index 1251ddd9a0273..4ec493e5f45e0 100644
--- a/clippy_lints/src/partialeq_ne_impl.rs
+++ b/clippy_lints/src/partialeq_ne_impl.rs
@@ -7,16 +7,16 @@ use rustc_session::{declare_lint_pass, declare_tool_lint};
 use rustc_span::sym;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for manual re-implementations of `PartialEq::ne`.
+    /// ### What it does
+    /// Checks for manual re-implementations of `PartialEq::ne`.
     ///
-    /// **Why is this bad?** `PartialEq::ne` is required to always return the
+    /// ### Why is this bad?
+    /// `PartialEq::ne` is required to always return the
     /// negated result of `PartialEq::eq`, which is exactly what the default
     /// implementation does. Therefore, there should never be any need to
     /// re-implement it.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// struct Foo;
     ///
diff --git a/clippy_lints/src/pass_by_ref_or_value.rs b/clippy_lints/src/pass_by_ref_or_value.rs
index f6a704785598e..f738ac2541788 100644
--- a/clippy_lints/src/pass_by_ref_or_value.rs
+++ b/clippy_lints/src/pass_by_ref_or_value.rs
@@ -20,15 +20,18 @@ use rustc_target::spec::abi::Abi;
 use rustc_target::spec::Target;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for functions taking arguments by reference, where
+    /// ### What it does
+    /// Checks for functions taking arguments by reference, where
     /// the argument type is `Copy` and small enough to be more efficient to always
     /// pass by value.
     ///
-    /// **Why is this bad?** In many calling conventions instances of structs will
+    /// ### Why is this bad?
+    /// In many calling conventions instances of structs will
     /// be passed through registers if they fit into two or less general purpose
     /// registers.
     ///
-    /// **Known problems:** This lint is target register size dependent, it is
+    /// ### Known problems
+    /// This lint is target register size dependent, it is
     /// limited to 32-bit to try and reduce portability problems between 32 and
     /// 64-bit, but if you are compiling for 8 or 16-bit targets then the limit
     /// will be different.
@@ -50,7 +53,7 @@ declare_clippy_lint! {
     /// that explains a real case in which this false positive
     /// led to an **undefined behaviour** introduced with unsafe code.
     ///
-    /// **Example:**
+    /// ### Example
     ///
     /// ```rust
     /// // Bad
@@ -67,18 +70,19 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for functions taking arguments by value, where
+    /// ### What it does
+    /// Checks for functions taking arguments by value, where
     /// the argument type is `Copy` and large enough to be worth considering
     /// passing by reference. Does not trigger if the function is being exported,
     /// because that might induce API breakage, if the parameter is declared as mutable,
     /// or if the argument is a `self`.
     ///
-    /// **Why is this bad?** Arguments passed by value might result in an unnecessary
+    /// ### Why is this bad?
+    /// Arguments passed by value might result in an unnecessary
     /// shallow copy, taking up more space in the stack and requiring a call to
     /// `memcpy`, which can be expensive.
     ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust
     /// #[derive(Clone, Copy)]
     /// struct TooLarge([u8; 2048]);
diff --git a/clippy_lints/src/path_buf_push_overwrite.rs b/clippy_lints/src/path_buf_push_overwrite.rs
index 0024592638104..3df7a72d29509 100644
--- a/clippy_lints/src/path_buf_push_overwrite.rs
+++ b/clippy_lints/src/path_buf_push_overwrite.rs
@@ -10,15 +10,15 @@ use rustc_span::symbol::sym;
 use std::path::{Component, Path};
 
 declare_clippy_lint! {
-    /// **What it does:*** Checks for [push](https://doc.rust-lang.org/std/path/struct.PathBuf.html#method.push)
+    /// ### What it does
+    ///* Checks for [push](https://doc.rust-lang.org/std/path/struct.PathBuf.html#method.push)
     /// calls on `PathBuf` that can cause overwrites.
     ///
-    /// **Why is this bad?** Calling `push` with a root path at the start can overwrite the
+    /// ### Why is this bad?
+    /// Calling `push` with a root path at the start can overwrite the
     /// previous defined path.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// use std::path::PathBuf;
     ///
diff --git a/clippy_lints/src/pattern_type_mismatch.rs b/clippy_lints/src/pattern_type_mismatch.rs
index ea4065d371b81..4534f6e251659 100644
--- a/clippy_lints/src/pattern_type_mismatch.rs
+++ b/clippy_lints/src/pattern_type_mismatch.rs
@@ -13,7 +13,8 @@ use rustc_span::source_map::Span;
 use std::iter;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for patterns that aren't exact representations of the types
+    /// ### What it does
+    /// Checks for patterns that aren't exact representations of the types
     /// they are applied to.
     ///
     /// To satisfy this lint, you will have to adjust either the expression that is matched
@@ -32,14 +33,12 @@ declare_clippy_lint! {
     /// this lint can still be used to highlight areas of interest and ensure a good understanding
     /// of ownership semantics.
     ///
-    /// **Why is this bad?** It isn't bad in general. But in some contexts it can be desirable
+    /// ### Why is this bad?
+    /// It isn't bad in general. But in some contexts it can be desirable
     /// because it increases ownership hints in the code, and will guard against some changes
     /// in ownership.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// This example shows the basic adjustments necessary to satisfy the lint. Note how
     /// the matched expression is explicitly dereferenced with `*` and the `inner` variable
     /// is bound to a shared borrow via `ref inner`.
diff --git a/clippy_lints/src/precedence.rs b/clippy_lints/src/precedence.rs
index 9cf00c953b95f..1a8da00d9d616 100644
--- a/clippy_lints/src/precedence.rs
+++ b/clippy_lints/src/precedence.rs
@@ -25,7 +25,8 @@ const ALLOWED_ODD_FUNCTIONS: [&str; 14] = [
 ];
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for operations where precedence may be unclear
+    /// ### What it does
+    /// Checks for operations where precedence may be unclear
     /// and suggests to add parentheses. Currently it catches the following:
     /// * mixed usage of arithmetic and bit shifting/combining operators without
     /// parentheses
@@ -33,13 +34,12 @@ declare_clippy_lint! {
     /// numeric literal)
     ///   followed by a method call
     ///
-    /// **Why is this bad?** Not everyone knows the precedence of those operators by
+    /// ### Why is this bad?
+    /// Not everyone knows the precedence of those operators by
     /// heart, so expressions like these may trip others trying to reason about the
     /// code.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// * `1 << 2 + 3` equals 32, while `(1 << 2) + 3` equals 7
     /// * `-1i32.abs()` equals -1, while `(-1i32).abs()` equals 1
     pub PRECEDENCE,
diff --git a/clippy_lints/src/ptr.rs b/clippy_lints/src/ptr.rs
index b15447622a8af..c0d1f1eb6e65e 100644
--- a/clippy_lints/src/ptr.rs
+++ b/clippy_lints/src/ptr.rs
@@ -20,16 +20,19 @@ use rustc_span::{sym, MultiSpan};
 use std::borrow::Cow;
 
 declare_clippy_lint! {
-    /// **What it does:** This lint checks for function arguments of type `&String`
+    /// ### What it does
+    /// This lint checks for function arguments of type `&String`
     /// or `&Vec` unless the references are mutable. It will also suggest you
     /// replace `.clone()` calls with the appropriate `.to_owned()`/`to_string()`
     /// calls.
     ///
-    /// **Why is this bad?** Requiring the argument to be of the specific size
+    /// ### Why is this bad?
+    /// Requiring the argument to be of the specific size
     /// makes the function less useful for no benefit; slices in the form of `&[T]`
     /// or `&str` usually suffice and can be obtained from other types, too.
     ///
-    /// **Known problems:** The lint does not follow data. So if you have an
+    /// ### Known problems
+    /// The lint does not follow data. So if you have an
     /// argument `x` and write `let y = x; y.clone()` the lint will not suggest
     /// changing that `.clone()` to `.to_owned()`.
     ///
@@ -59,7 +62,7 @@ declare_clippy_lint! {
     /// other crates referencing it, of which you may not be aware. Carefully
     /// deprecate the function before applying the lint suggestions in this case.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```ignore
     /// // Bad
     /// fn foo(&Vec<u32>) { .. }
@@ -73,15 +76,15 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** This lint checks for equality comparisons with `ptr::null`
+    /// ### What it does
+    /// This lint checks for equality comparisons with `ptr::null`
     ///
-    /// **Why is this bad?** It's easier and more readable to use the inherent
+    /// ### Why is this bad?
+    /// It's easier and more readable to use the inherent
     /// `.is_null()`
     /// method instead
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```ignore
     /// // Bad
     /// if x == ptr::null {
@@ -99,19 +102,22 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** This lint checks for functions that take immutable
+    /// ### What it does
+    /// This lint checks for functions that take immutable
     /// references and return mutable ones.
     ///
-    /// **Why is this bad?** This is trivially unsound, as one can create two
+    /// ### Why is this bad?
+    /// This is trivially unsound, as one can create two
     /// mutable references from the same (immutable!) source.
     /// This [error](https://github.com/rust-lang/rust/issues/39465)
     /// actually lead to an interim Rust release 1.15.1.
     ///
-    /// **Known problems:** To be on the conservative side, if there's at least one
+    /// ### Known problems
+    /// To be on the conservative side, if there's at least one
     /// mutable reference with the output lifetime, this lint will not trigger.
     /// In practice, this case is unlikely anyway.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```ignore
     /// fn foo(&Foo) -> &mut Bar { .. }
     /// ```
@@ -121,13 +127,13 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** This lint checks for invalid usages of `ptr::null`.
-    ///
-    /// **Why is this bad?** This causes undefined behavior.
+    /// ### What it does
+    /// This lint checks for invalid usages of `ptr::null`.
     ///
-    /// **Known problems:** None.
+    /// ### Why is this bad?
+    /// This causes undefined behavior.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```ignore
     /// // Bad. Undefined behavior
     /// unsafe { std::slice::from_raw_parts(ptr::null(), 0); }
diff --git a/clippy_lints/src/ptr_eq.rs b/clippy_lints/src/ptr_eq.rs
index 77cfa3f6b176c..d6d7049fb61b2 100644
--- a/clippy_lints/src/ptr_eq.rs
+++ b/clippy_lints/src/ptr_eq.rs
@@ -8,16 +8,15 @@ use rustc_lint::{LateContext, LateLintPass};
 use rustc_session::{declare_lint_pass, declare_tool_lint};
 
 declare_clippy_lint! {
-    /// **What it does:** Use `std::ptr::eq` when applicable
+    /// ### What it does
+    /// Use `std::ptr::eq` when applicable
     ///
-    /// **Why is this bad?** `ptr::eq` can be used to compare `&T` references
+    /// ### Why is this bad?
+    /// `ptr::eq` can be used to compare `&T` references
     /// (which coerce to `*const T` implicitly) by their address rather than
     /// comparing the values they point to.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust
     /// let a = &[1, 2, 3];
     /// let b = &[1, 2, 3];
diff --git a/clippy_lints/src/ptr_offset_with_cast.rs b/clippy_lints/src/ptr_offset_with_cast.rs
index afb198f49559a..f1975056ddc9b 100644
--- a/clippy_lints/src/ptr_offset_with_cast.rs
+++ b/clippy_lints/src/ptr_offset_with_cast.rs
@@ -8,15 +8,15 @@ use rustc_span::sym;
 use std::fmt;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for usage of the `offset` pointer method with a `usize` casted to an
+    /// ### What it does
+    /// Checks for usage of the `offset` pointer method with a `usize` casted to an
     /// `isize`.
     ///
-    /// **Why is this bad?** If we’re always increasing the pointer address, we can avoid the numeric
+    /// ### Why is this bad?
+    /// If we’re always increasing the pointer address, we can avoid the numeric
     /// cast by using the `add` method instead.
     ///
-    /// **Known problems:** None
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// let vec = vec![b'a', b'b', b'c'];
     /// let ptr = vec.as_ptr();
diff --git a/clippy_lints/src/question_mark.rs b/clippy_lints/src/question_mark.rs
index d66bac5224360..0e682c692c7a6 100644
--- a/clippy_lints/src/question_mark.rs
+++ b/clippy_lints/src/question_mark.rs
@@ -13,13 +13,13 @@ use rustc_session::{declare_lint_pass, declare_tool_lint};
 use rustc_span::sym;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for expressions that could be replaced by the question mark operator.
+    /// ### What it does
+    /// Checks for expressions that could be replaced by the question mark operator.
     ///
-    /// **Why is this bad?** Question mark usage is more idiomatic.
+    /// ### Why is this bad?
+    /// Question mark usage is more idiomatic.
     ///
-    /// **Known problems:** None
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```ignore
     /// if option.is_none() {
     ///     return None;
diff --git a/clippy_lints/src/ranges.rs b/clippy_lints/src/ranges.rs
index b41c478c26615..0179bd48ee3cb 100644
--- a/clippy_lints/src/ranges.rs
+++ b/clippy_lints/src/ranges.rs
@@ -18,14 +18,14 @@ use rustc_span::symbol::Ident;
 use std::cmp::Ordering;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for zipping a collection with the range of
+    /// ### What it does
+    /// Checks for zipping a collection with the range of
     /// `0.._.len()`.
     ///
-    /// **Why is this bad?** The code is better expressed with `.enumerate()`.
+    /// ### Why is this bad?
+    /// The code is better expressed with `.enumerate()`.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # let x = vec![1];
     /// x.iter().zip(0..x.len());
@@ -41,13 +41,16 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for exclusive ranges where 1 is added to the
+    /// ### What it does
+    /// Checks for exclusive ranges where 1 is added to the
     /// upper bound, e.g., `x..(y+1)`.
     ///
-    /// **Why is this bad?** The code is more readable with an inclusive range
+    /// ### Why is this bad?
+    /// The code is more readable with an inclusive range
     /// like `x..=y`.
     ///
-    /// **Known problems:** Will add unnecessary pair of parentheses when the
+    /// ### Known problems
+    /// Will add unnecessary pair of parentheses when the
     /// expression is not wrapped in a pair but starts with a opening parenthesis
     /// and ends with a closing one.
     /// I.e., `let _ = (f()+1)..(f()+1)` results in `let _ = ((f()+1)..=f())`.
@@ -61,7 +64,7 @@ declare_clippy_lint! {
     /// `RangeBounds` trait
     /// ([#3307](https://github.com/rust-lang/rust-clippy/issues/3307)).
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust,ignore
     /// for x..(y+1) { .. }
     /// ```
@@ -75,18 +78,21 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for inclusive ranges where 1 is subtracted from
+    /// ### What it does
+    /// Checks for inclusive ranges where 1 is subtracted from
     /// the upper bound, e.g., `x..=(y-1)`.
     ///
-    /// **Why is this bad?** The code is more readable with an exclusive range
+    /// ### Why is this bad?
+    /// The code is more readable with an exclusive range
     /// like `x..y`.
     ///
-    /// **Known problems:** This will cause a warning that cannot be fixed if
+    /// ### Known problems
+    /// This will cause a warning that cannot be fixed if
     /// the consumer of the range only accepts a specific range type, instead of
     /// the generic `RangeBounds` trait
     /// ([#3307](https://github.com/rust-lang/rust-clippy/issues/3307)).
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust,ignore
     /// for x..=(y-1) { .. }
     /// ```
@@ -100,16 +106,15 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for range expressions `x..y` where both `x` and `y`
+    /// ### What it does
+    /// Checks for range expressions `x..y` where both `x` and `y`
     /// are constant and `x` is greater or equal to `y`.
     ///
-    /// **Why is this bad?** Empty ranges yield no values so iterating them is a no-op.
+    /// ### Why is this bad?
+    /// Empty ranges yield no values so iterating them is a no-op.
     /// Moreover, trying to use a reversed range to index a slice will panic at run-time.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust,no_run
     /// fn main() {
     ///     (10..=0).for_each(|x| println!("{}", x));
@@ -133,16 +138,15 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for expressions like `x >= 3 && x < 8` that could
+    /// ### What it does
+    /// Checks for expressions like `x >= 3 && x < 8` that could
     /// be more readably expressed as `(3..8).contains(x)`.
     ///
-    /// **Why is this bad?** `contains` expresses the intent better and has less
+    /// ### Why is this bad?
+    /// `contains` expresses the intent better and has less
     /// failure modes (such as fencepost errors or using `||` instead of `&&`).
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust
     /// // given
     /// let x = 6;
diff --git a/clippy_lints/src/redundant_clone.rs b/clippy_lints/src/redundant_clone.rs
index 56ef95a88c880..530b3396abef6 100644
--- a/clippy_lints/src/redundant_clone.rs
+++ b/clippy_lints/src/redundant_clone.rs
@@ -32,17 +32,18 @@ macro_rules! unwrap_or_continue {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for a redundant `clone()` (and its relatives) which clones an owned
+    /// ### What it does
+    /// Checks for a redundant `clone()` (and its relatives) which clones an owned
     /// value that is going to be dropped without further use.
     ///
-    /// **Why is this bad?** It is not always possible for the compiler to eliminate useless
+    /// ### Why is this bad?
+    /// It is not always possible for the compiler to eliminate useless
     /// allocations and deallocations generated by redundant `clone()`s.
     ///
-    /// **Known problems:**
-    ///
+    /// ### Known problems
     /// False-negatives: analysis performed by this lint is conservative and limited.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # use std::path::Path;
     /// # #[derive(Clone)]
diff --git a/clippy_lints/src/redundant_closure_call.rs b/clippy_lints/src/redundant_closure_call.rs
index 8f56a21ac5b3d..a79b2fe76e2d5 100644
--- a/clippy_lints/src/redundant_closure_call.rs
+++ b/clippy_lints/src/redundant_closure_call.rs
@@ -14,15 +14,15 @@ use rustc_middle::lint::in_external_macro;
 use rustc_session::{declare_lint_pass, declare_tool_lint};
 
 declare_clippy_lint! {
-    /// **What it does:** Detects closures called in the same expression where they
+    /// ### What it does
+    /// Detects closures called in the same expression where they
     /// are defined.
     ///
-    /// **Why is this bad?** It is unnecessarily adding to the expression's
+    /// ### Why is this bad?
+    /// It is unnecessarily adding to the expression's
     /// complexity.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust,ignore
     /// // Bad
     /// let a = (|| 42)()
diff --git a/clippy_lints/src/redundant_else.rs b/clippy_lints/src/redundant_else.rs
index 061526c6f09fa..68b256d29442a 100644
--- a/clippy_lints/src/redundant_else.rs
+++ b/clippy_lints/src/redundant_else.rs
@@ -6,14 +6,16 @@ use rustc_middle::lint::in_external_macro;
 use rustc_session::{declare_lint_pass, declare_tool_lint};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for `else` blocks that can be removed without changing semantics.
+    /// ### What it does
+    /// Checks for `else` blocks that can be removed without changing semantics.
     ///
-    /// **Why is this bad?** The `else` block adds unnecessary indentation and verbosity.
+    /// ### Why is this bad?
+    /// The `else` block adds unnecessary indentation and verbosity.
     ///
-    /// **Known problems:** Some may prefer to keep the `else` block for clarity.
-    ///
-    /// **Example:**
+    /// ### Known problems
+    /// Some may prefer to keep the `else` block for clarity.
     ///
+    /// ### Example
     /// ```rust
     /// fn my_func(count: u32) {
     ///     if count == 0 {
diff --git a/clippy_lints/src/redundant_field_names.rs b/clippy_lints/src/redundant_field_names.rs
index d5ee8d3468deb..47df4917510ff 100644
--- a/clippy_lints/src/redundant_field_names.rs
+++ b/clippy_lints/src/redundant_field_names.rs
@@ -8,15 +8,15 @@ use rustc_semver::RustcVersion;
 use rustc_session::{declare_tool_lint, impl_lint_pass};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for fields in struct literals where shorthands
+    /// ### What it does
+    /// Checks for fields in struct literals where shorthands
     /// could be used.
     ///
-    /// **Why is this bad?** If the field and variable names are the same,
+    /// ### Why is this bad?
+    /// If the field and variable names are the same,
     /// the field name is redundant.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// let bar: u8 = 123;
     ///
diff --git a/clippy_lints/src/redundant_pub_crate.rs b/clippy_lints/src/redundant_pub_crate.rs
index 05f9e01acb44b..59a55b9dffad4 100644
--- a/clippy_lints/src/redundant_pub_crate.rs
+++ b/clippy_lints/src/redundant_pub_crate.rs
@@ -5,16 +5,15 @@ use rustc_lint::{LateContext, LateLintPass};
 use rustc_session::{declare_tool_lint, impl_lint_pass};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for items declared `pub(crate)` that are not crate visible because they
+    /// ### What it does
+    /// Checks for items declared `pub(crate)` that are not crate visible because they
     /// are inside a private module.
     ///
-    /// **Why is this bad?** Writing `pub(crate)` is misleading when it's redundant due to the parent
+    /// ### Why is this bad?
+    /// Writing `pub(crate)` is misleading when it's redundant due to the parent
     /// module's visibility.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust
     /// mod internal {
     ///     pub(crate) fn internal_fn() { }
diff --git a/clippy_lints/src/redundant_slicing.rs b/clippy_lints/src/redundant_slicing.rs
index 9c6cd7b4fa625..290348c4509ec 100644
--- a/clippy_lints/src/redundant_slicing.rs
+++ b/clippy_lints/src/redundant_slicing.rs
@@ -10,17 +10,19 @@ use rustc_middle::ty::TyS;
 use rustc_session::{declare_lint_pass, declare_tool_lint};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for redundant slicing expressions which use the full range, and
+    /// ### What it does
+    /// Checks for redundant slicing expressions which use the full range, and
     /// do not change the type.
     ///
-    /// **Why is this bad?** It unnecessarily adds complexity to the expression.
+    /// ### Why is this bad?
+    /// It unnecessarily adds complexity to the expression.
     ///
-    /// **Known problems:** If the type being sliced has an implementation of `Index<RangeFull>`
+    /// ### Known problems
+    /// If the type being sliced has an implementation of `Index<RangeFull>`
     /// that actually changes anything then it can't be removed. However, this would be surprising
     /// to people reading the code and should have a note with it.
     ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```ignore
     /// fn get_slice(x: &[u32]) -> &[u32] {
     ///     &x[..]
diff --git a/clippy_lints/src/redundant_static_lifetimes.rs b/clippy_lints/src/redundant_static_lifetimes.rs
index 48107d9c037db..d5a1a61da6bf4 100644
--- a/clippy_lints/src/redundant_static_lifetimes.rs
+++ b/clippy_lints/src/redundant_static_lifetimes.rs
@@ -8,14 +8,14 @@ use rustc_semver::RustcVersion;
 use rustc_session::{declare_tool_lint, impl_lint_pass};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for constants and statics with an explicit `'static` lifetime.
+    /// ### What it does
+    /// Checks for constants and statics with an explicit `'static` lifetime.
     ///
-    /// **Why is this bad?** Adding `'static` to every reference can create very
+    /// ### Why is this bad?
+    /// Adding `'static` to every reference can create very
     /// complicated types.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```ignore
     /// const FOO: &'static [(&'static str, &'static str, fn(&Bar) -> bool)] =
     /// &[...]
diff --git a/clippy_lints/src/ref_option_ref.rs b/clippy_lints/src/ref_option_ref.rs
index 0cf4e0ce7fe22..65ab6cac44219 100644
--- a/clippy_lints/src/ref_option_ref.rs
+++ b/clippy_lints/src/ref_option_ref.rs
@@ -9,16 +9,18 @@ use rustc_session::{declare_lint_pass, declare_tool_lint};
 use rustc_span::symbol::sym;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for usage of `&Option<&T>`.
+    /// ### What it does
+    /// Checks for usage of `&Option<&T>`.
     ///
-    /// **Why is this bad?** Since `&` is Copy, it's useless to have a
+    /// ### Why is this bad?
+    /// Since `&` is Copy, it's useless to have a
     /// reference on `Option<&T>`.
     ///
-    /// **Known problems:** It may be irrelevant to use this lint on
+    /// ### Known problems
+    /// It may be irrelevant to use this lint on
     /// public API code as it will make a breaking change to apply it.
     ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust,ignore
     /// let x: &Option<&u32> = &Some(&0u32);
     /// ```
diff --git a/clippy_lints/src/reference.rs b/clippy_lints/src/reference.rs
index d6336389b0af1..e0930d69ab9fe 100644
--- a/clippy_lints/src/reference.rs
+++ b/clippy_lints/src/reference.rs
@@ -10,15 +10,18 @@ use rustc_session::{declare_lint_pass, declare_tool_lint};
 use rustc_span::BytePos;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for usage of `*&` and `*&mut` in expressions.
+    /// ### What it does
+    /// Checks for usage of `*&` and `*&mut` in expressions.
     ///
-    /// **Why is this bad?** Immediately dereferencing a reference is no-op and
+    /// ### Why is this bad?
+    /// Immediately dereferencing a reference is no-op and
     /// makes the code less clear.
     ///
-    /// **Known problems:** Multiple dereference/addrof pairs are not handled so
+    /// ### Known problems
+    /// Multiple dereference/addrof pairs are not handled so
     /// the suggested fix for `x = **&&y` is `x = *&y`, which is still incorrect.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust,ignore
     /// // Bad
     /// let a = f(*&mut b);
@@ -101,13 +104,15 @@ impl EarlyLintPass for DerefAddrOf {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for references in expressions that use
+    /// ### What it does
+    /// Checks for references in expressions that use
     /// auto dereference.
     ///
-    /// **Why is this bad?** The reference is a no-op and is automatically
+    /// ### Why is this bad?
+    /// The reference is a no-op and is automatically
     /// dereferenced by the compiler and makes the code less clear.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// struct Point(u32, u32);
     /// let point = Point(30, 20);
diff --git a/clippy_lints/src/regex.rs b/clippy_lints/src/regex.rs
index 751511674542d..eab097337306b 100644
--- a/clippy_lints/src/regex.rs
+++ b/clippy_lints/src/regex.rs
@@ -11,15 +11,15 @@ use rustc_span::source_map::{BytePos, Span};
 use std::convert::TryFrom;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks [regex](https://crates.io/crates/regex) creation
+    /// ### What it does
+    /// Checks [regex](https://crates.io/crates/regex) creation
     /// (with `Regex::new`, `RegexBuilder::new`, or `RegexSet::new`) for correct
     /// regex syntax.
     ///
-    /// **Why is this bad?** This will lead to a runtime panic.
+    /// ### Why is this bad?
+    /// This will lead to a runtime panic.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```ignore
     /// Regex::new("|")
     /// ```
@@ -29,18 +29,21 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for trivial [regex](https://crates.io/crates/regex)
+    /// ### What it does
+    /// Checks for trivial [regex](https://crates.io/crates/regex)
     /// creation (with `Regex::new`, `RegexBuilder::new`, or `RegexSet::new`).
     ///
-    /// **Why is this bad?** Matching the regex can likely be replaced by `==` or
+    /// ### Why is this bad?
+    /// Matching the regex can likely be replaced by `==` or
     /// `str::starts_with`, `str::ends_with` or `std::contains` or other `str`
     /// methods.
     ///
-    /// **Known problems:** If the same regex is going to be applied to multiple
+    /// ### Known problems
+    /// If the same regex is going to be applied to multiple
     /// inputs, the precomputations done by `Regex` construction can give
     /// significantly better performance than any of the `str`-based methods.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```ignore
     /// Regex::new("^foobar")
     /// ```
diff --git a/clippy_lints/src/repeat_once.rs b/clippy_lints/src/repeat_once.rs
index 17cb96bc4ebd1..54b9c8b3275c6 100644
--- a/clippy_lints/src/repeat_once.rs
+++ b/clippy_lints/src/repeat_once.rs
@@ -11,7 +11,8 @@ use rustc_session::{declare_lint_pass, declare_tool_lint};
 use rustc_span::sym;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for usage of `.repeat(1)` and suggest the following method for each types.
+    /// ### What it does
+    /// Checks for usage of `.repeat(1)` and suggest the following method for each types.
     /// - `.to_string()` for `str`
     /// - `.clone()` for `String`
     /// - `.to_vec()` for `slice`
@@ -19,13 +20,11 @@ declare_clippy_lint! {
     /// The lint will evaluate constant expressions and values as arguments of `.repeat(..)` and emit a message if
     /// they are equivalent to `1`. (Related discussion in [rust-clippy#7306](https://github.com/rust-lang/rust-clippy/issues/7306))
     ///
-    /// **Why is this bad?** For example, `String.repeat(1)` is equivalent to `.clone()`. If cloning
+    /// ### Why is this bad?
+    /// For example, `String.repeat(1)` is equivalent to `.clone()`. If cloning
     /// the string is the intention behind this, `clone()` should be used.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust
     /// fn main() {
     ///     let x = String::from("hello world").repeat(1);
diff --git a/clippy_lints/src/returns.rs b/clippy_lints/src/returns.rs
index 251d527c26522..db4b1002ce129 100644
--- a/clippy_lints/src/returns.rs
+++ b/clippy_lints/src/returns.rs
@@ -15,15 +15,15 @@ use rustc_span::source_map::Span;
 use rustc_span::sym;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for `let`-bindings, which are subsequently
+    /// ### What it does
+    /// Checks for `let`-bindings, which are subsequently
     /// returned.
     ///
-    /// **Why is this bad?** It is just extraneous code. Remove it to make your code
+    /// ### Why is this bad?
+    /// It is just extraneous code. Remove it to make your code
     /// more rusty.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// fn foo() -> String {
     ///     let x = String::new();
@@ -42,14 +42,14 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for return statements at the end of a block.
+    /// ### What it does
+    /// Checks for return statements at the end of a block.
     ///
-    /// **Why is this bad?** Removing the `return` and semicolon will make the code
+    /// ### Why is this bad?
+    /// Removing the `return` and semicolon will make the code
     /// more rusty.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// fn foo(x: usize) -> usize {
     ///     return x;
diff --git a/clippy_lints/src/self_assignment.rs b/clippy_lints/src/self_assignment.rs
index e7925c4fbdeff..fbd65fef7d11b 100644
--- a/clippy_lints/src/self_assignment.rs
+++ b/clippy_lints/src/self_assignment.rs
@@ -6,16 +6,18 @@ use rustc_lint::{LateContext, LateLintPass};
 use rustc_session::{declare_lint_pass, declare_tool_lint};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for explicit self-assignments.
+    /// ### What it does
+    /// Checks for explicit self-assignments.
     ///
-    /// **Why is this bad?** Self-assignments are redundant and unlikely to be
+    /// ### Why is this bad?
+    /// Self-assignments are redundant and unlikely to be
     /// intentional.
     ///
-    /// **Known problems:** If expression contains any deref coercions or
+    /// ### Known problems
+    /// If expression contains any deref coercions or
     /// indexing operations they are assumed not to have any side effects.
     ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust
     /// struct Event {
     ///     id: usize,
diff --git a/clippy_lints/src/self_named_constructor.rs b/clippy_lints/src/self_named_constructor.rs
index da991e1d90c8e..2123a14cc1b82 100644
--- a/clippy_lints/src/self_named_constructor.rs
+++ b/clippy_lints/src/self_named_constructor.rs
@@ -6,14 +6,13 @@ use rustc_lint::{LateContext, LateLintPass};
 use rustc_session::{declare_lint_pass, declare_tool_lint};
 
 declare_clippy_lint! {
-    /// **What it does:** Warns when constructors have the same name as their types.
+    /// ### What it does
+    /// Warns when constructors have the same name as their types.
     ///
-    /// **Why is this bad?** Repeating the name of the type is redundant.
-    ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Why is this bad?
+    /// Repeating the name of the type is redundant.
     ///
+    /// ### Example
     /// ```rust,ignore
     /// struct Foo {}
     ///
diff --git a/clippy_lints/src/semicolon_if_nothing_returned.rs b/clippy_lints/src/semicolon_if_nothing_returned.rs
index da3e30af35ca4..6966230156cfa 100644
--- a/clippy_lints/src/semicolon_if_nothing_returned.rs
+++ b/clippy_lints/src/semicolon_if_nothing_returned.rs
@@ -9,16 +9,15 @@ use rustc_lint::{LateContext, LateLintPass};
 use rustc_session::{declare_lint_pass, declare_tool_lint};
 
 declare_clippy_lint! {
-    /// **What it does:** Looks for blocks of expressions and fires if the last expression returns
+    /// ### What it does
+    /// Looks for blocks of expressions and fires if the last expression returns
     /// `()` but is not followed by a semicolon.
     ///
-    /// **Why is this bad?** The semicolon might be optional but when extending the block with new
+    /// ### Why is this bad?
+    /// The semicolon might be optional but when extending the block with new
     /// code, it doesn't require a change in previous last line.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust
     /// fn main() {
     ///     println!("Hello world")
diff --git a/clippy_lints/src/serde_api.rs b/clippy_lints/src/serde_api.rs
index 169f7d26285cd..2cd0f85999cf5 100644
--- a/clippy_lints/src/serde_api.rs
+++ b/clippy_lints/src/serde_api.rs
@@ -5,14 +5,15 @@ use rustc_lint::{LateContext, LateLintPass};
 use rustc_session::{declare_lint_pass, declare_tool_lint};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for mis-uses of the serde API.
+    /// ### What it does
+    /// Checks for mis-uses of the serde API.
     ///
-    /// **Why is this bad?** Serde is very finnicky about how its API should be
+    /// ### Why is this bad?
+    /// Serde is very finnicky about how its API should be
     /// used, but the type system can't be used to enforce it (yet?).
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:** Implementing `Visitor::visit_string` but not
+    /// ### Example
+    /// Implementing `Visitor::visit_string` but not
     /// `Visitor::visit_str`.
     pub SERDE_API_MISUSE,
     correctness,
diff --git a/clippy_lints/src/shadow.rs b/clippy_lints/src/shadow.rs
index ac3f7ebd14bd8..b28a37cabd40c 100644
--- a/clippy_lints/src/shadow.rs
+++ b/clippy_lints/src/shadow.rs
@@ -14,17 +14,20 @@ use rustc_span::source_map::Span;
 use rustc_span::symbol::Symbol;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for bindings that shadow other bindings already in
+    /// ### What it does
+    /// Checks for bindings that shadow other bindings already in
     /// scope, while just changing reference level or mutability.
     ///
-    /// **Why is this bad?** Not much, in fact it's a very common pattern in Rust
+    /// ### Why is this bad?
+    /// Not much, in fact it's a very common pattern in Rust
     /// code. Still, some may opt to avoid it in their code base, they can set this
     /// lint to `Warn`.
     ///
-    /// **Known problems:** This lint, as the other shadowing related lints,
+    /// ### Known problems
+    /// This lint, as the other shadowing related lints,
     /// currently only catches very simple patterns.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # let x = 1;
     /// // Bad
@@ -39,18 +42,21 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for bindings that shadow other bindings already in
+    /// ### What it does
+    /// Checks for bindings that shadow other bindings already in
     /// scope, while reusing the original value.
     ///
-    /// **Why is this bad?** Not too much, in fact it's a common pattern in Rust
+    /// ### Why is this bad?
+    /// Not too much, in fact it's a common pattern in Rust
     /// code. Still, some argue that name shadowing like this hurts readability,
     /// because a value may be bound to different things depending on position in
     /// the code.
     ///
-    /// **Known problems:** This lint, as the other shadowing related lints,
+    /// ### Known problems
+    /// This lint, as the other shadowing related lints,
     /// currently only catches very simple patterns.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// let x = 2;
     /// let x = x + 1;
@@ -66,21 +72,24 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for bindings that shadow other bindings already in
+    /// ### What it does
+    /// Checks for bindings that shadow other bindings already in
     /// scope, either without a initialization or with one that does not even use
     /// the original value.
     ///
-    /// **Why is this bad?** Name shadowing can hurt readability, especially in
+    /// ### Why is this bad?
+    /// Name shadowing can hurt readability, especially in
     /// large code bases, because it is easy to lose track of the active binding at
     /// any place in the code. This can be alleviated by either giving more specific
     /// names to bindings or introducing more scopes to contain the bindings.
     ///
-    /// **Known problems:** This lint, as the other shadowing related lints,
+    /// ### Known problems
+    /// This lint, as the other shadowing related lints,
     /// currently only catches very simple patterns. Note that
     /// `allow`/`warn`/`deny`/`forbid` attributes only work on the function level
     /// for this lint.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # let y = 1;
     /// # let z = 2;
diff --git a/clippy_lints/src/single_component_path_imports.rs b/clippy_lints/src/single_component_path_imports.rs
index 1eaad438237ec..f6487b8c46bd4 100644
--- a/clippy_lints/src/single_component_path_imports.rs
+++ b/clippy_lints/src/single_component_path_imports.rs
@@ -7,15 +7,14 @@ use rustc_session::{declare_lint_pass, declare_tool_lint};
 use rustc_span::{edition::Edition, symbol::kw, Span, Symbol};
 
 declare_clippy_lint! {
-    /// **What it does:** Checking for imports with single component use path.
+    /// ### What it does
+    /// Checking for imports with single component use path.
     ///
-    /// **Why is this bad?** Import with single component use path such as `use cratename;`
+    /// ### Why is this bad?
+    /// Import with single component use path such as `use cratename;`
     /// is not necessary, and thus should be removed.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust,ignore
     /// use regex;
     ///
diff --git a/clippy_lints/src/size_of_in_element_count.rs b/clippy_lints/src/size_of_in_element_count.rs
index b1965cfd601b1..3e4e4a8d0c08b 100644
--- a/clippy_lints/src/size_of_in_element_count.rs
+++ b/clippy_lints/src/size_of_in_element_count.rs
@@ -11,16 +11,16 @@ use rustc_middle::ty::{self, Ty, TyS, TypeAndMut};
 use rustc_session::{declare_lint_pass, declare_tool_lint};
 
 declare_clippy_lint! {
-    /// **What it does:** Detects expressions where
+    /// ### What it does
+    /// Detects expressions where
     /// `size_of::<T>` or `size_of_val::<T>` is used as a
     /// count of elements of type `T`
     ///
-    /// **Why is this bad?** These functions expect a count
+    /// ### Why is this bad?
+    /// These functions expect a count
     /// of `T` and not a number of bytes
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust,no_run
     /// # use std::ptr::copy_nonoverlapping;
     /// # use std::mem::size_of;
diff --git a/clippy_lints/src/slow_vector_initialization.rs b/clippy_lints/src/slow_vector_initialization.rs
index e5c58d70b603e..3d039e1306560 100644
--- a/clippy_lints/src/slow_vector_initialization.rs
+++ b/clippy_lints/src/slow_vector_initialization.rs
@@ -13,14 +13,14 @@ use rustc_session::{declare_lint_pass, declare_tool_lint};
 use rustc_span::symbol::sym;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks slow zero-filled vector initialization
+    /// ### What it does
+    /// Checks slow zero-filled vector initialization
     ///
-    /// **Why is this bad?** These structures are non-idiomatic and less efficient than simply using
+    /// ### Why is this bad?
+    /// These structures are non-idiomatic and less efficient than simply using
     /// `vec![0; len]`.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # use core::iter::repeat;
     /// # let len = 4;
diff --git a/clippy_lints/src/stable_sort_primitive.rs b/clippy_lints/src/stable_sort_primitive.rs
index 65790375c7379..4ea1293d504d3 100644
--- a/clippy_lints/src/stable_sort_primitive.rs
+++ b/clippy_lints/src/stable_sort_primitive.rs
@@ -7,22 +7,18 @@ use rustc_lint::{LateContext, LateLintPass};
 use rustc_session::{declare_lint_pass, declare_tool_lint};
 
 declare_clippy_lint! {
-    /// **What it does:**
+    /// ### What it does
     /// When sorting primitive values (integers, bools, chars, as well
     /// as arrays, slices, and tuples of such items), it is better to
     /// use an unstable sort than a stable sort.
     ///
-    /// **Why is this bad?**
+    /// ### Why is this bad?
     /// Using a stable sort consumes more memory and cpu cycles. Because
     /// values which compare equal are identical, preserving their
     /// relative order (the guarantee that a stable sort provides) means
     /// nothing, while the extra costs still apply.
     ///
-    /// **Known problems:**
-    /// None
-    ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust
     /// let mut vec = vec![2, 1, 3];
     /// vec.sort();
diff --git a/clippy_lints/src/strings.rs b/clippy_lints/src/strings.rs
index 958e462125ef1..1a78a4968e5a3 100644
--- a/clippy_lints/src/strings.rs
+++ b/clippy_lints/src/strings.rs
@@ -14,16 +14,15 @@ use rustc_span::source_map::Spanned;
 use rustc_span::sym;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for string appends of the form `x = x + y` (without
+    /// ### What it does
+    /// Checks for string appends of the form `x = x + y` (without
     /// `let`!).
     ///
-    /// **Why is this bad?** It's not really bad, but some people think that the
+    /// ### Why is this bad?
+    /// It's not really bad, but some people think that the
     /// `.push_str(_)` method is more readable.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust
     /// let mut x = "Hello".to_owned();
     /// x = x + ", World";
@@ -38,11 +37,13 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for all instances of `x + _` where `x` is of type
+    /// ### What it does
+    /// Checks for all instances of `x + _` where `x` is of type
     /// `String`, but only if [`string_add_assign`](#string_add_assign) does *not*
     /// match.
     ///
-    /// **Why is this bad?** It's not bad in and of itself. However, this particular
+    /// ### Why is this bad?
+    /// It's not bad in and of itself. However, this particular
     /// `Add` implementation is asymmetric (the other operand need not be `String`,
     /// but `x` does), while addition as mathematically defined is symmetric, also
     /// the `String::push_str(_)` function is a perfectly good replacement.
@@ -52,10 +53,7 @@ declare_clippy_lint! {
     /// in other languages is actually fine, which is why we decided to make this
     /// particular lint `allow` by default.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust
     /// let x = "Hello".to_owned();
     /// x + ", World";
@@ -66,13 +64,15 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for the `as_bytes` method called on string literals
+    /// ### What it does
+    /// Checks for the `as_bytes` method called on string literals
     /// that contain only ASCII characters.
     ///
-    /// **Why is this bad?** Byte string literals (e.g., `b"foo"`) can be used
+    /// ### Why is this bad?
+    /// Byte string literals (e.g., `b"foo"`) can be used
     /// instead. They are shorter but less discoverable than `as_bytes()`.
     ///
-    /// **Known Problems:**
+    /// ### Known problems
     /// `"str".as_bytes()` and the suggested replacement of `b"str"` are not
     /// equivalent because they have different types. The former is `&[u8]`
     /// while the latter is `&[u8; 3]`. That means in general they will have a
@@ -94,7 +94,7 @@ declare_clippy_lint! {
     /// `b"str"` but `&b"str"[..]`, which is a great deal of punctuation and not
     /// more readable than a function call.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// // Bad
     /// let bs = "a byte string".as_bytes();
@@ -177,13 +177,13 @@ fn is_add(cx: &LateContext<'_>, src: &Expr<'_>, target: &Expr<'_>) -> bool {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Check if the string is transformed to byte array and casted back to string.
+    /// ### What it does
+    /// Check if the string is transformed to byte array and casted back to string.
     ///
-    /// **Why is this bad?** It's unnecessary, the string can be used directly.
+    /// ### Why is this bad?
+    /// It's unnecessary, the string can be used directly.
     ///
-    /// **Known problems:** None
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// let _ = std::str::from_utf8(&"Hello World!".as_bytes()[6..11]).unwrap();
     /// ```
@@ -317,16 +317,15 @@ impl<'tcx> LateLintPass<'tcx> for StringLitAsBytes {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** This lint checks for `.to_string()` method calls on values of type `&str`.
+    /// ### What it does
+    /// This lint checks for `.to_string()` method calls on values of type `&str`.
     ///
-    /// **Why is this bad?** The `to_string` method is also used on other types to convert them to a string.
+    /// ### Why is this bad?
+    /// The `to_string` method is also used on other types to convert them to a string.
     /// When called on a `&str` it turns the `&str` into the owned variant `String`, which can be better
     /// expressed with `.to_owned()`.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust
     /// // example code where clippy issues a warning
     /// let _ = "str".to_string();
@@ -366,14 +365,14 @@ impl LateLintPass<'_> for StrToString {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** This lint checks for `.to_string()` method calls on values of type `String`.
+    /// ### What it does
+    /// This lint checks for `.to_string()` method calls on values of type `String`.
     ///
-    /// **Why is this bad?** The `to_string` method is also used on other types to convert them to a string.
+    /// ### Why is this bad?
+    /// The `to_string` method is also used on other types to convert them to a string.
     /// When called on a `String` it only clones the `String`, which can be better expressed with `.clone()`.
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
     ///
+    /// ### Example
     /// ```rust
     /// // example code where clippy issues a warning
     /// let msg = String::from("Hello World");
diff --git a/clippy_lints/src/strlen_on_c_strings.rs b/clippy_lints/src/strlen_on_c_strings.rs
index 2ccf3a3796d51..516fa3d95b428 100644
--- a/clippy_lints/src/strlen_on_c_strings.rs
+++ b/clippy_lints/src/strlen_on_c_strings.rs
@@ -11,16 +11,15 @@ use rustc_session::{declare_lint_pass, declare_tool_lint};
 use rustc_span::symbol::{sym, Symbol};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for usage of `libc::strlen` on a `CString` or `CStr` value,
+    /// ### What it does
+    /// Checks for usage of `libc::strlen` on a `CString` or `CStr` value,
     /// and suggest calling `as_bytes().len()` or `to_bytes().len()` respectively instead.
     ///
-    /// **Why is this bad?** This avoids calling an unsafe `libc` function.
+    /// ### Why is this bad?
+    /// This avoids calling an unsafe `libc` function.
     /// Currently, it also avoids calculating the length.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust, ignore
     /// use std::ffi::CString;
     /// let cstring = CString::new("foo").expect("CString::new failed");
diff --git a/clippy_lints/src/suspicious_operation_groupings.rs b/clippy_lints/src/suspicious_operation_groupings.rs
index bb707f78fccd8..a8e962d1af3fa 100644
--- a/clippy_lints/src/suspicious_operation_groupings.rs
+++ b/clippy_lints/src/suspicious_operation_groupings.rs
@@ -13,20 +13,21 @@ use rustc_span::symbol::Ident;
 use rustc_span::Span;
 
 declare_clippy_lint! {
-    /// **What it does:**
+    /// ### What it does
     /// Checks for unlikely usages of binary operators that are almost
     /// certainly typos and/or copy/paste errors, given the other usages
     /// of binary operators nearby.
-    /// **Why is this bad?**
+    ///
+    /// ### Why is this bad?
     /// They are probably bugs and if they aren't then they look like bugs
     /// and you should add a comment explaining why you are doing such an
     /// odd set of operations.
-    /// **Known problems:**
+    ///
+    /// ### Known problems
     /// There may be some false positives if you are trying to do something
     /// unusual that happens to look like a typo.
     ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust
     /// struct Vec3 {
     ///     x: f64,
diff --git a/clippy_lints/src/suspicious_trait_impl.rs b/clippy_lints/src/suspicious_trait_impl.rs
index f2bffd553210b..682fad00a13ee 100644
--- a/clippy_lints/src/suspicious_trait_impl.rs
+++ b/clippy_lints/src/suspicious_trait_impl.rs
@@ -8,14 +8,14 @@ use rustc_middle::hir::map::Map;
 use rustc_session::{declare_lint_pass, declare_tool_lint};
 
 declare_clippy_lint! {
-    /// **What it does:** Lints for suspicious operations in impls of arithmetic operators, e.g.
+    /// ### What it does
+    /// Lints for suspicious operations in impls of arithmetic operators, e.g.
     /// subtracting elements in an Add impl.
     ///
-    /// **Why this is bad?** This is probably a typo or copy-and-paste error and not intended.
+    /// ### Why is this bad?
+    /// This is probably a typo or copy-and-paste error and not intended.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```ignore
     /// impl Add for Foo {
     ///     type Output = Foo;
@@ -31,14 +31,14 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Lints for suspicious operations in impls of OpAssign, e.g.
+    /// ### What it does
+    /// Lints for suspicious operations in impls of OpAssign, e.g.
     /// subtracting elements in an AddAssign impl.
     ///
-    /// **Why this is bad?** This is probably a typo or copy-and-paste error and not intended.
-    ///
-    /// **Known problems:** None.
+    /// ### Why is this bad?
+    /// This is probably a typo or copy-and-paste error and not intended.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```ignore
     /// impl AddAssign for Foo {
     ///     fn add_assign(&mut self, other: Foo) {
diff --git a/clippy_lints/src/swap.rs b/clippy_lints/src/swap.rs
index 19967e2c97014..4fa8e77a67b78 100644
--- a/clippy_lints/src/swap.rs
+++ b/clippy_lints/src/swap.rs
@@ -12,14 +12,14 @@ use rustc_session::{declare_lint_pass, declare_tool_lint};
 use rustc_span::sym;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for manual swapping.
+    /// ### What it does
+    /// Checks for manual swapping.
     ///
-    /// **Why is this bad?** The `std::mem::swap` function exposes the intent better
+    /// ### Why is this bad?
+    /// The `std::mem::swap` function exposes the intent better
     /// without deinitializing or copying either variable.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// let mut a = 42;
     /// let mut b = 1337;
@@ -40,13 +40,13 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for `foo = bar; bar = foo` sequences.
-    ///
-    /// **Why is this bad?** This looks like a failed attempt to swap.
+    /// ### What it does
+    /// Checks for `foo = bar; bar = foo` sequences.
     ///
-    /// **Known problems:** None.
+    /// ### Why is this bad?
+    /// This looks like a failed attempt to swap.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # let mut a = 1;
     /// # let mut b = 2;
diff --git a/clippy_lints/src/tabs_in_doc_comments.rs b/clippy_lints/src/tabs_in_doc_comments.rs
index e2c144709f5b7..6a73b94d87e48 100644
--- a/clippy_lints/src/tabs_in_doc_comments.rs
+++ b/clippy_lints/src/tabs_in_doc_comments.rs
@@ -7,16 +7,16 @@ use rustc_span::source_map::{BytePos, Span};
 use std::convert::TryFrom;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks doc comments for usage of tab characters.
+    /// ### What it does
+    /// Checks doc comments for usage of tab characters.
     ///
-    /// **Why is this bad?** The rust style-guide promotes spaces instead of tabs for indentation.
+    /// ### Why is this bad?
+    /// The rust style-guide promotes spaces instead of tabs for indentation.
     /// To keep a consistent view on the source, also doc comments should not have tabs.
     /// Also, explaining ascii-diagrams containing tabs can get displayed incorrectly when the
     /// display settings of the author and reader differ.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// ///
     /// /// Struct to hold two strings:
diff --git a/clippy_lints/src/temporary_assignment.rs b/clippy_lints/src/temporary_assignment.rs
index 8ef25dc816c65..a9da690339ccf 100644
--- a/clippy_lints/src/temporary_assignment.rs
+++ b/clippy_lints/src/temporary_assignment.rs
@@ -5,15 +5,15 @@ use rustc_lint::{LateContext, LateLintPass};
 use rustc_session::{declare_lint_pass, declare_tool_lint};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for construction of a structure or tuple just to
+    /// ### What it does
+    /// Checks for construction of a structure or tuple just to
     /// assign a value in it.
     ///
-    /// **Why is this bad?** Readability. If the structure is only created to be
+    /// ### Why is this bad?
+    /// Readability. If the structure is only created to be
     /// updated, why not write the structure you want in the first place?
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// (0, 0).0 = 1
     /// ```
diff --git a/clippy_lints/src/to_digit_is_some.rs b/clippy_lints/src/to_digit_is_some.rs
index c66a596c78461..1c14a9199950c 100644
--- a/clippy_lints/src/to_digit_is_some.rs
+++ b/clippy_lints/src/to_digit_is_some.rs
@@ -9,12 +9,14 @@ use rustc_middle::ty;
 use rustc_session::{declare_lint_pass, declare_tool_lint};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for `.to_digit(..).is_some()` on `char`s.
+    /// ### What it does
+    /// Checks for `.to_digit(..).is_some()` on `char`s.
     ///
-    /// **Why is this bad?** This is a convoluted way of checking if a `char` is a digit. It's
+    /// ### Why is this bad?
+    /// This is a convoluted way of checking if a `char` is a digit. It's
     /// more straight forward to use the dedicated `is_digit` method.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # let c = 'c';
     /// # let radix = 10;
diff --git a/clippy_lints/src/to_string_in_display.rs b/clippy_lints/src/to_string_in_display.rs
index 4fb297ac6c699..b036ed9a3d2e7 100644
--- a/clippy_lints/src/to_string_in_display.rs
+++ b/clippy_lints/src/to_string_in_display.rs
@@ -7,15 +7,15 @@ use rustc_session::{declare_tool_lint, impl_lint_pass};
 use rustc_span::symbol::sym;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for uses of `to_string()` in `Display` traits.
+    /// ### What it does
+    /// Checks for uses of `to_string()` in `Display` traits.
     ///
-    /// **Why is this bad?** Usually `to_string` is implemented indirectly
+    /// ### Why is this bad?
+    /// Usually `to_string` is implemented indirectly
     /// via `Display`. Hence using it while implementing `Display` would
     /// lead to infinite recursion.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     ///
     /// ```rust
     /// use std::fmt;
diff --git a/clippy_lints/src/trait_bounds.rs b/clippy_lints/src/trait_bounds.rs
index 74a94db180006..79367c4230c2a 100644
--- a/clippy_lints/src/trait_bounds.rs
+++ b/clippy_lints/src/trait_bounds.rs
@@ -11,14 +11,14 @@ use rustc_session::{declare_tool_lint, impl_lint_pass};
 use rustc_span::Span;
 
 declare_clippy_lint! {
-    /// **What it does:** This lint warns about unnecessary type repetitions in trait bounds
+    /// ### What it does
+    /// This lint warns about unnecessary type repetitions in trait bounds
     ///
-    /// **Why is this bad?** Repeating the type for every bound makes the code
+    /// ### Why is this bad?
+    /// Repeating the type for every bound makes the code
     /// less readable than combining the bounds
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// pub fn foo<T>(t: T) where T: Copy, T: Clone {}
     /// ```
@@ -34,15 +34,15 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for cases where generics are being used and multiple
+    /// ### What it does
+    /// Checks for cases where generics are being used and multiple
     /// syntax specifications for trait bounds are used simultaneously.
     ///
-    /// **Why is this bad?** Duplicate bounds makes the code
+    /// ### Why is this bad?
+    /// Duplicate bounds makes the code
     /// less readable than specifing them only once.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// fn func<T: Clone + Default>(arg: T) where T: Clone + Default {}
     /// ```
diff --git a/clippy_lints/src/transmute/mod.rs b/clippy_lints/src/transmute/mod.rs
index 89fd5faa165f4..33ec9c331ce56 100644
--- a/clippy_lints/src/transmute/mod.rs
+++ b/clippy_lints/src/transmute/mod.rs
@@ -20,15 +20,18 @@ use rustc_session::{declare_lint_pass, declare_tool_lint};
 use rustc_span::symbol::sym;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for transmutes that can't ever be correct on any
+    /// ### What it does
+    /// Checks for transmutes that can't ever be correct on any
     /// architecture.
     ///
-    /// **Why is this bad?** It's basically guaranteed to be undefined behaviour.
+    /// ### Why is this bad?
+    /// It's basically guaranteed to be undefined behaviour.
     ///
-    /// **Known problems:** When accessing C, users might want to store pointer
+    /// ### Known problems
+    /// When accessing C, users might want to store pointer
     /// sized objects in `extradata` arguments to save an allocation.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```ignore
     /// let ptr: *const T = core::intrinsics::transmute('x')
     /// ```
@@ -39,15 +42,15 @@ declare_clippy_lint! {
 
 // FIXME: Move this to `complexity` again, after #5343 is fixed
 declare_clippy_lint! {
-    /// **What it does:** Checks for transmutes to the original type of the object
+    /// ### What it does
+    /// Checks for transmutes to the original type of the object
     /// and transmutes that could be a cast.
     ///
-    /// **Why is this bad?** Readability. The code tricks people into thinking that
+    /// ### Why is this bad?
+    /// Readability. The code tricks people into thinking that
     /// something complex is going on.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust,ignore
     /// core::intrinsics::transmute(t); // where the result type is the same as `t`'s
     /// ```
@@ -58,14 +61,14 @@ declare_clippy_lint! {
 
 // FIXME: Merge this lint with USELESS_TRANSMUTE once that is out of the nursery.
 declare_clippy_lint! {
-    /// **What it does:**Checks for transmutes that could be a pointer cast.
+    /// ### What it does
+    ///Checks for transmutes that could be a pointer cast.
     ///
-    /// **Why is this bad?** Readability. The code tricks people into thinking that
+    /// ### Why is this bad?
+    /// Readability. The code tricks people into thinking that
     /// something complex is going on.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     ///
     /// ```rust
     /// # let p: *const [i32] = &[];
@@ -82,14 +85,14 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for transmutes between a type `T` and `*T`.
+    /// ### What it does
+    /// Checks for transmutes between a type `T` and `*T`.
     ///
-    /// **Why is this bad?** It's easy to mistakenly transmute between a type and a
+    /// ### Why is this bad?
+    /// It's easy to mistakenly transmute between a type and a
     /// pointer to that type.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust,ignore
     /// core::intrinsics::transmute(t) // where the result type is the same as
     ///                                // `*t` or `&t`'s
@@ -100,17 +103,19 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for transmutes from a pointer to a reference.
+    /// ### What it does
+    /// Checks for transmutes from a pointer to a reference.
     ///
-    /// **Why is this bad?** This can always be rewritten with `&` and `*`.
+    /// ### Why is this bad?
+    /// This can always be rewritten with `&` and `*`.
     ///
-    /// **Known problems:**
+    /// ### Known problems
     /// - `mem::transmute` in statics and constants is stable from Rust 1.46.0,
     /// while dereferencing raw pointer is not stable yet.
     /// If you need to do this in those places,
     /// you would have to use `transmute` instead.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust,ignore
     /// unsafe {
     ///     let _: &T = std::mem::transmute(p); // where p: *const T
@@ -125,11 +130,13 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for transmutes from an integer to a `char`.
+    /// ### What it does
+    /// Checks for transmutes from an integer to a `char`.
     ///
-    /// **Why is this bad?** Not every integer is a Unicode scalar value.
+    /// ### Why is this bad?
+    /// Not every integer is a Unicode scalar value.
     ///
-    /// **Known problems:**
+    /// ### Known problems
     /// - [`from_u32`] which this lint suggests using is slower than `transmute`
     /// as it needs to validate the input.
     /// If you are certain that the input is always a valid Unicode scalar value,
@@ -140,7 +147,7 @@ declare_clippy_lint! {
     /// [`from_u32`]: https://doc.rust-lang.org/std/char/fn.from_u32.html
     /// [`from_u32_unchecked`]: https://doc.rust-lang.org/std/char/fn.from_u32_unchecked.html
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// let x = 1_u32;
     /// unsafe {
@@ -156,11 +163,13 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for transmutes from a `&[u8]` to a `&str`.
+    /// ### What it does
+    /// Checks for transmutes from a `&[u8]` to a `&str`.
     ///
-    /// **Why is this bad?** Not every byte slice is a valid UTF-8 string.
+    /// ### Why is this bad?
+    /// Not every byte slice is a valid UTF-8 string.
     ///
-    /// **Known problems:**
+    /// ### Known problems
     /// - [`from_utf8`] which this lint suggests using is slower than `transmute`
     /// as it needs to validate the input.
     /// If you are certain that the input is always a valid UTF-8,
@@ -171,7 +180,7 @@ declare_clippy_lint! {
     /// [`from_utf8`]: https://doc.rust-lang.org/std/str/fn.from_utf8.html
     /// [`from_utf8_unchecked`]: https://doc.rust-lang.org/std/str/fn.from_utf8_unchecked.html
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// let b: &[u8] = &[1_u8, 2_u8];
     /// unsafe {
@@ -187,13 +196,13 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for transmutes from an integer to a `bool`.
-    ///
-    /// **Why is this bad?** This might result in an invalid in-memory representation of a `bool`.
+    /// ### What it does
+    /// Checks for transmutes from an integer to a `bool`.
     ///
-    /// **Known problems:** None.
+    /// ### Why is this bad?
+    /// This might result in an invalid in-memory representation of a `bool`.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// let x = 1_u8;
     /// unsafe {
@@ -209,14 +218,14 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for transmutes from an integer to a float.
+    /// ### What it does
+    /// Checks for transmutes from an integer to a float.
     ///
-    /// **Why is this bad?** Transmutes are dangerous and error-prone, whereas `from_bits` is intuitive
+    /// ### Why is this bad?
+    /// Transmutes are dangerous and error-prone, whereas `from_bits` is intuitive
     /// and safe.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// unsafe {
     ///     let _: f32 = std::mem::transmute(1_u32); // where x: u32
@@ -231,14 +240,14 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for transmutes from a float to an integer.
+    /// ### What it does
+    /// Checks for transmutes from a float to an integer.
     ///
-    /// **Why is this bad?** Transmutes are dangerous and error-prone, whereas `to_bits` is intuitive
+    /// ### Why is this bad?
+    /// Transmutes are dangerous and error-prone, whereas `to_bits` is intuitive
     /// and safe.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// unsafe {
     ///     let _: u32 = std::mem::transmute(1f32);
@@ -253,15 +262,15 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for transmutes from a pointer to a pointer, or
+    /// ### What it does
+    /// Checks for transmutes from a pointer to a pointer, or
     /// from a reference to a reference.
     ///
-    /// **Why is this bad?** Transmutes are dangerous, and these can instead be
+    /// ### Why is this bad?
+    /// Transmutes are dangerous, and these can instead be
     /// written as casts.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// let ptr = &1u32 as *const u32;
     /// unsafe {
@@ -280,15 +289,18 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for transmutes between collections whose
+    /// ### What it does
+    /// Checks for transmutes between collections whose
     /// types have different ABI, size or alignment.
     ///
-    /// **Why is this bad?** This is undefined behavior.
+    /// ### Why is this bad?
+    /// This is undefined behavior.
     ///
-    /// **Known problems:** Currently, we cannot know whether a type is a
+    /// ### Known problems
+    /// Currently, we cannot know whether a type is a
     /// collection, so we just lint the ones that come with `std`.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// // different size, therefore likely out-of-bounds memory access
     /// // You absolutely do not want this in your code!
diff --git a/clippy_lints/src/transmuting_null.rs b/clippy_lints/src/transmuting_null.rs
index 0c39d4d8cf466..a67fa7922059c 100644
--- a/clippy_lints/src/transmuting_null.rs
+++ b/clippy_lints/src/transmuting_null.rs
@@ -10,15 +10,18 @@ use rustc_session::{declare_lint_pass, declare_tool_lint};
 use rustc_span::symbol::sym;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for transmute calls which would receive a null pointer.
+    /// ### What it does
+    /// Checks for transmute calls which would receive a null pointer.
     ///
-    /// **Why is this bad?** Transmuting a null pointer is undefined behavior.
+    /// ### Why is this bad?
+    /// Transmuting a null pointer is undefined behavior.
     ///
-    /// **Known problems:** Not all cases can be detected at the moment of this writing.
+    /// ### Known problems
+    /// Not all cases can be detected at the moment of this writing.
     /// For example, variables which hold a null pointer and are then fed to a `transmute`
     /// call, aren't detectable yet.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// let null_ref: &u64 = unsafe { std::mem::transmute(0 as *const u64) };
     /// ```
diff --git a/clippy_lints/src/try_err.rs b/clippy_lints/src/try_err.rs
index f2ba2b2ecf639..1196271d5dd13 100644
--- a/clippy_lints/src/try_err.rs
+++ b/clippy_lints/src/try_err.rs
@@ -13,16 +13,16 @@ use rustc_session::{declare_lint_pass, declare_tool_lint};
 use rustc_span::sym;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for usages of `Err(x)?`.
+    /// ### What it does
+    /// Checks for usages of `Err(x)?`.
     ///
-    /// **Why is this bad?** The `?` operator is designed to allow calls that
+    /// ### Why is this bad?
+    /// The `?` operator is designed to allow calls that
     /// can fail to be easily chained. For example, `foo()?.bar()` or
     /// `foo(bar()?)`. Because `Err(x)?` can't be used that way (it will
     /// always return), it is more clear to write `return Err(x)`.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// fn foo(fail: bool) -> Result<i32, String> {
     ///     if fail {
diff --git a/clippy_lints/src/types/mod.rs b/clippy_lints/src/types/mod.rs
index 7d629b5455b62..ad7409fe3a9b7 100644
--- a/clippy_lints/src/types/mod.rs
+++ b/clippy_lints/src/types/mod.rs
@@ -20,16 +20,16 @@ use rustc_session::{declare_tool_lint, impl_lint_pass};
 use rustc_span::source_map::Span;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for use of `Box<Vec<_>>` anywhere in the code.
+    /// ### What it does
+    /// Checks for use of `Box<Vec<_>>` anywhere in the code.
     /// Check the [Box documentation](https://doc.rust-lang.org/std/boxed/index.html) for more information.
     ///
-    /// **Why is this bad?** `Vec` already keeps its contents in a separate area on
+    /// ### Why is this bad?
+    /// `Vec` already keeps its contents in a separate area on
     /// the heap. So if you `Box` it, you just add another level of indirection
     /// without any benefit whatsoever.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust,ignore
     /// struct X {
     ///     values: Box<Vec<Foo>>,
@@ -49,16 +49,19 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for use of `Vec<Box<T>>` where T: Sized anywhere in the code.
+    /// ### What it does
+    /// Checks for use of `Vec<Box<T>>` where T: Sized anywhere in the code.
     /// Check the [Box documentation](https://doc.rust-lang.org/std/boxed/index.html) for more information.
     ///
-    /// **Why is this bad?** `Vec` already keeps its contents in a separate area on
+    /// ### Why is this bad?
+    /// `Vec` already keeps its contents in a separate area on
     /// the heap. So if you `Box` its contents, you just add another level of indirection.
     ///
-    /// **Known problems:** Vec<Box<T: Sized>> makes sense if T is a large type (see [#3530](https://github.com/rust-lang/rust-clippy/issues/3530),
+    /// ### Known problems
+    /// Vec<Box<T: Sized>> makes sense if T is a large type (see [#3530](https://github.com/rust-lang/rust-clippy/issues/3530),
     /// 1st comment).
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// struct X {
     ///     values: Vec<Box<i32>>,
@@ -78,19 +81,19 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for use of `Option<Option<_>>` in function signatures and type
+    /// ### What it does
+    /// Checks for use of `Option<Option<_>>` in function signatures and type
     /// definitions
     ///
-    /// **Why is this bad?** `Option<_>` represents an optional value. `Option<Option<_>>`
+    /// ### Why is this bad?
+    /// `Option<_>` represents an optional value. `Option<Option<_>>`
     /// represents an optional optional value which is logically the same thing as an optional
     /// value but has an unneeded extra level of wrapping.
     ///
     /// If you have a case where `Some(Some(_))`, `Some(None)` and `None` are distinct cases,
     /// consider a custom `enum` instead, with clear names for each case.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example**
+    /// ### Example
     /// ```rust
     /// fn get_data() -> Option<Option<u32>> {
     ///     None
@@ -116,10 +119,12 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for usage of any `LinkedList`, suggesting to use a
+    /// ### What it does
+    /// Checks for usage of any `LinkedList`, suggesting to use a
     /// `Vec` or a `VecDeque` (formerly called `RingBuf`).
     ///
-    /// **Why is this bad?** Gankro says:
+    /// ### Why is this bad?
+    /// Gankro says:
     ///
     /// > The TL;DR of `LinkedList` is that it's built on a massive amount of
     /// pointers and indirection.
@@ -138,10 +143,11 @@ declare_clippy_lint! {
     /// can still be better
     /// > because of how expensive it is to seek to the middle of a `LinkedList`.
     ///
-    /// **Known problems:** False positives – the instances where using a
+    /// ### Known problems
+    /// False positives – the instances where using a
     /// `LinkedList` makes sense are few and far between, but they can still happen.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # use std::collections::LinkedList;
     /// let x: LinkedList<usize> = LinkedList::new();
@@ -152,15 +158,15 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for use of `&Box<T>` anywhere in the code.
+    /// ### What it does
+    /// Checks for use of `&Box<T>` anywhere in the code.
     /// Check the [Box documentation](https://doc.rust-lang.org/std/boxed/index.html) for more information.
     ///
-    /// **Why is this bad?** Any `&Box<T>` can also be a `&T`, which is more
+    /// ### Why is this bad?
+    /// Any `&Box<T>` can also be a `&T`, which is more
     /// general.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust,ignore
     /// fn foo(bar: &Box<T>) { ... }
     /// ```
@@ -176,14 +182,14 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for use of redundant allocations anywhere in the code.
+    /// ### What it does
+    /// Checks for use of redundant allocations anywhere in the code.
     ///
-    /// **Why is this bad?** Expressions such as `Rc<&T>`, `Rc<Rc<T>>`, `Rc<Arc<T>>`, `Rc<Box<T>>`, Arc<&T>`, `Arc<Rc<T>>`,
+    /// ### Why is this bad?
+    /// Expressions such as `Rc<&T>`, `Rc<Rc<T>>`, `Rc<Arc<T>>`, `Rc<Box<T>>`, Arc<&T>`, `Arc<Rc<T>>`,
     /// `Arc<Arc<T>>`, `Arc<Box<T>>`, `Box<&T>`, `Box<Rc<T>>`, `Box<Arc<T>>`, `Box<Box<T>>`, add an unnecessary level of indirection.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # use std::rc::Rc;
     /// fn foo(bar: Rc<&usize>) {}
@@ -200,9 +206,11 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for `Rc<T>` and `Arc<T>` when `T` is a mutable buffer type such as `String` or `Vec`.
+    /// ### What it does
+    /// Checks for `Rc<T>` and `Arc<T>` when `T` is a mutable buffer type such as `String` or `Vec`.
     ///
-    /// **Why is this bad?** Expressions such as `Rc<String>` usually have no advantage over `Rc<str>`, since
+    /// ### Why is this bad?
+    /// Expressions such as `Rc<String>` usually have no advantage over `Rc<str>`, since
     /// it is larger and involves an extra level of indirection, and doesn't implement `Borrow<str>`.
     ///
     /// While mutating a buffer type would still be possible with `Rc::get_mut()`, it only
@@ -211,10 +219,11 @@ declare_clippy_lint! {
     /// type with an interior mutable container (such as `RefCell` or `Mutex`) would normally
     /// be used.
     ///
-    /// **Known problems:** This pattern can be desirable to avoid the overhead of a `RefCell` or `Mutex` for
+    /// ### Known problems
+    /// This pattern can be desirable to avoid the overhead of a `RefCell` or `Mutex` for
     /// cases where mutation only happens before there are any additional references.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust,ignore
     /// # use std::rc::Rc;
     /// fn foo(interned: Rc<String>) { ... }
@@ -231,15 +240,15 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for types used in structs, parameters and `let`
+    /// ### What it does
+    /// Checks for types used in structs, parameters and `let`
     /// declarations above a certain complexity threshold.
     ///
-    /// **Why is this bad?** Too complex types make the code less readable. Consider
+    /// ### Why is this bad?
+    /// Too complex types make the code less readable. Consider
     /// using a `type` definition to simplify them.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # use std::rc::Rc;
     /// struct Foo {
@@ -252,16 +261,19 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for `Rc<Mutex<T>>`.
+    /// ### What it does
+    /// Checks for `Rc<Mutex<T>>`.
     ///
-    /// **Why is this bad?** `Rc` is used in single thread and `Mutex` is used in multi thread.
+    /// ### Why is this bad?
+    /// `Rc` is used in single thread and `Mutex` is used in multi thread.
     /// Consider using `Rc<RefCell<T>>` in single thread or `Arc<Mutex<T>>` in multi thread.
     ///
-    /// **Known problems:** Sometimes combining generic types can lead to the requirement that a
+    /// ### Known problems
+    /// Sometimes combining generic types can lead to the requirement that a
     /// type use Rc in conjunction with Mutex. We must consider those cases false positives, but
     /// alas they are quite hard to rule out. Luckily they are also rare.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust,ignore
     /// use std::rc::Rc;
     /// use std::sync::Mutex;
diff --git a/clippy_lints/src/undropped_manually_drops.rs b/clippy_lints/src/undropped_manually_drops.rs
index f4f5e1233e351..47571e608c780 100644
--- a/clippy_lints/src/undropped_manually_drops.rs
+++ b/clippy_lints/src/undropped_manually_drops.rs
@@ -6,15 +6,17 @@ use rustc_lint::{LateContext, LateLintPass};
 use rustc_session::{declare_lint_pass, declare_tool_lint};
 
 declare_clippy_lint! {
-    /// **What it does:** Prevents the safe `std::mem::drop` function from being called on `std::mem::ManuallyDrop`.
+    /// ### What it does
+    /// Prevents the safe `std::mem::drop` function from being called on `std::mem::ManuallyDrop`.
     ///
-    /// **Why is this bad?** The safe `drop` function does not drop the inner value of a `ManuallyDrop`.
+    /// ### Why is this bad?
+    /// The safe `drop` function does not drop the inner value of a `ManuallyDrop`.
     ///
-    /// **Known problems:** Does not catch cases if the user binds `std::mem::drop`
+    /// ### Known problems
+    /// Does not catch cases if the user binds `std::mem::drop`
     /// to a different name and calls it that way.
     ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust
     /// struct S;
     /// drop(std::mem::ManuallyDrop::new(S));
diff --git a/clippy_lints/src/unicode.rs b/clippy_lints/src/unicode.rs
index 2f0a61898ba75..f337dec8f2b96 100644
--- a/clippy_lints/src/unicode.rs
+++ b/clippy_lints/src/unicode.rs
@@ -10,14 +10,15 @@ use rustc_span::source_map::Span;
 use unicode_normalization::UnicodeNormalization;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for invisible Unicode characters in the code.
+    /// ### What it does
+    /// Checks for invisible Unicode characters in the code.
     ///
-    /// **Why is this bad?** Having an invisible character in the code makes for all
+    /// ### Why is this bad?
+    /// Having an invisible character in the code makes for all
     /// sorts of April fools, but otherwise is very much frowned upon.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:** You don't see it, but there may be a zero-width space or soft hyphen
+    /// ### Example
+    /// You don't see it, but there may be a zero-width space or soft hyphen
     /// some­where in this text.
     pub INVISIBLE_CHARACTERS,
     correctness,
@@ -25,17 +26,17 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for non-ASCII characters in string literals.
+    /// ### What it does
+    /// Checks for non-ASCII characters in string literals.
     ///
-    /// **Why is this bad?** Yeah, we know, the 90's called and wanted their charset
+    /// ### Why is this bad?
+    /// Yeah, we know, the 90's called and wanted their charset
     /// back. Even so, there still are editors and other programs out there that
     /// don't work well with Unicode. So if the code is meant to be used
     /// internationally, on multiple operating systems, or has other portability
     /// requirements, activating this lint could be useful.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// let x = String::from("€");
     /// ```
@@ -49,16 +50,17 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for string literals that contain Unicode in a form
+    /// ### What it does
+    /// Checks for string literals that contain Unicode in a form
     /// that is not equal to its
     /// [NFC-recomposition](http://www.unicode.org/reports/tr15/#Norm_Forms).
     ///
-    /// **Why is this bad?** If such a string is compared to another, the results
+    /// ### Why is this bad?
+    /// If such a string is compared to another, the results
     /// may be surprising.
     ///
-    /// **Known problems** None.
-    ///
-    /// **Example:** You may not see it, but "à"" and "à"" aren't the same string. The
+    /// ### Example
+    /// You may not see it, but "à"" and "à"" aren't the same string. The
     /// former when escaped is actually `"a\u{300}"` while the latter is `"\u{e0}"`.
     pub UNICODE_NOT_NFC,
     pedantic,
diff --git a/clippy_lints/src/unit_return_expecting_ord.rs b/clippy_lints/src/unit_return_expecting_ord.rs
index 1c420a5042721..900d453176071 100644
--- a/clippy_lints/src/unit_return_expecting_ord.rs
+++ b/clippy_lints/src/unit_return_expecting_ord.rs
@@ -10,20 +10,22 @@ use rustc_session::{declare_lint_pass, declare_tool_lint};
 use rustc_span::{BytePos, Span};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for functions that expect closures of type
+    /// ### What it does
+    /// Checks for functions that expect closures of type
     /// Fn(...) -> Ord where the implemented closure returns the unit type.
     /// The lint also suggests to remove the semi-colon at the end of the statement if present.
     ///
-    /// **Why is this bad?** Likely, returning the unit type is unintentional, and
+    /// ### Why is this bad?
+    /// Likely, returning the unit type is unintentional, and
     /// could simply be caused by an extra semi-colon. Since () implements Ord
     /// it doesn't cause a compilation error.
     /// This is the same reasoning behind the unit_cmp lint.
     ///
-    /// **Known problems:** If returning unit is intentional, then there is no
+    /// ### Known problems
+    /// If returning unit is intentional, then there is no
     /// way of specifying this without triggering needless_return lint
     ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust
     /// let mut twins = vec!((1, 1), (2, 2));
     /// twins.sort_by_key(|x| { x.1; });
diff --git a/clippy_lints/src/unit_types/mod.rs b/clippy_lints/src/unit_types/mod.rs
index 64420a0393349..66b1abbe50b9d 100644
--- a/clippy_lints/src/unit_types/mod.rs
+++ b/clippy_lints/src/unit_types/mod.rs
@@ -8,14 +8,14 @@ use rustc_lint::{LateContext, LateLintPass};
 use rustc_session::{declare_lint_pass, declare_tool_lint};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for binding a unit value.
+    /// ### What it does
+    /// Checks for binding a unit value.
     ///
-    /// **Why is this bad?** A unit value cannot usefully be used anywhere. So
+    /// ### Why is this bad?
+    /// A unit value cannot usefully be used anywhere. So
     /// binding one is kind of pointless.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// let x = {
     ///     1;
@@ -27,16 +27,16 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for comparisons to unit. This includes all binary
+    /// ### What it does
+    /// Checks for comparisons to unit. This includes all binary
     /// comparisons (like `==` and `<`) and asserts.
     ///
-    /// **Why is this bad?** Unit is always equal to itself, and thus is just a
+    /// ### Why is this bad?
+    /// Unit is always equal to itself, and thus is just a
     /// clumsily written constant. Mostly this happens when someone accidentally
     /// adds semicolons at the end of the operands.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # fn foo() {};
     /// # fn bar() {};
@@ -74,14 +74,14 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for passing a unit value as an argument to a function without using a
+    /// ### What it does
+    /// Checks for passing a unit value as an argument to a function without using a
     /// unit literal (`()`).
     ///
-    /// **Why is this bad?** This is likely the result of an accidental semicolon.
-    ///
-    /// **Known problems:** None.
+    /// ### Why is this bad?
+    /// This is likely the result of an accidental semicolon.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust,ignore
     /// foo({
     ///     let a = bar();
diff --git a/clippy_lints/src/unnamed_address.rs b/clippy_lints/src/unnamed_address.rs
index 9cca05b1f1a65..1eafdee03521c 100644
--- a/clippy_lints/src/unnamed_address.rs
+++ b/clippy_lints/src/unnamed_address.rs
@@ -7,16 +7,15 @@ use rustc_middle::ty;
 use rustc_session::{declare_lint_pass, declare_tool_lint};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for comparisons with an address of a function item.
+    /// ### What it does
+    /// Checks for comparisons with an address of a function item.
     ///
-    /// **Why is this bad?** Function item address is not guaranteed to be unique and could vary
+    /// ### Why is this bad?
+    /// Function item address is not guaranteed to be unique and could vary
     /// between different code generation units. Furthermore different function items could have
     /// the same address after being merged together.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust
     /// type F = fn();
     /// fn a() {}
@@ -31,17 +30,16 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for comparisons with an address of a trait vtable.
+    /// ### What it does
+    /// Checks for comparisons with an address of a trait vtable.
     ///
-    /// **Why is this bad?** Comparing trait objects pointers compares an vtable addresses which
+    /// ### Why is this bad?
+    /// Comparing trait objects pointers compares an vtable addresses which
     /// are not guaranteed to be unique and could vary between different code generation units.
     /// Furthermore vtables for different types could have the same address after being merged
     /// together.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust,ignore
     /// let a: Rc<dyn Trait> = ...
     /// let b: Rc<dyn Trait> = ...
diff --git a/clippy_lints/src/unnecessary_self_imports.rs b/clippy_lints/src/unnecessary_self_imports.rs
index 48c54d79cf113..4cfd2df551f1b 100644
--- a/clippy_lints/src/unnecessary_self_imports.rs
+++ b/clippy_lints/src/unnecessary_self_imports.rs
@@ -7,16 +7,18 @@ use rustc_session::{declare_lint_pass, declare_tool_lint};
 use rustc_span::symbol::kw;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for imports ending in `::{self}`.
+    /// ### What it does
+    /// Checks for imports ending in `::{self}`.
     ///
-    /// **Why is this bad?** In most cases, this can be written much more cleanly by omitting `::{self}`.
+    /// ### Why is this bad?
+    /// In most cases, this can be written much more cleanly by omitting `::{self}`.
     ///
-    /// **Known problems:** Removing `::{self}` will cause any non-module items at the same path to also be imported.
+    /// ### Known problems
+    /// Removing `::{self}` will cause any non-module items at the same path to also be imported.
     /// This might cause a naming conflict (https://github.com/rust-lang/rustfmt/issues/3568). This lint makes no attempt
     /// to detect this scenario and that is why it is a restriction lint.
     ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust
     /// use std::io::{self};
     /// ```
diff --git a/clippy_lints/src/unnecessary_sort_by.rs b/clippy_lints/src/unnecessary_sort_by.rs
index 347d858b64026..6fc5707a4eeff 100644
--- a/clippy_lints/src/unnecessary_sort_by.rs
+++ b/clippy_lints/src/unnecessary_sort_by.rs
@@ -12,21 +12,20 @@ use rustc_span::symbol::Ident;
 use std::iter;
 
 declare_clippy_lint! {
-    /// **What it does:**
+    /// ### What it does
     /// Detects uses of `Vec::sort_by` passing in a closure
     /// which compares the two arguments, either directly or indirectly.
     ///
-    /// **Why is this bad?**
+    /// ### Why is this bad?
     /// It is more clear to use `Vec::sort_by_key` (or `Vec::sort` if
     /// possible) than to use `Vec::sort_by` and a more complicated
     /// closure.
     ///
-    /// **Known problems:**
+    /// ### Known problems
     /// If the suggested `Vec::sort_by_key` uses Reverse and it isn't already
     /// imported by a use statement, then it will need to be added manually.
     ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust
     /// # struct A;
     /// # impl A { fn foo(&self) {} }
diff --git a/clippy_lints/src/unnecessary_wraps.rs b/clippy_lints/src/unnecessary_wraps.rs
index a85ffa6aa9505..7a62b21937ff0 100644
--- a/clippy_lints/src/unnecessary_wraps.rs
+++ b/clippy_lints/src/unnecessary_wraps.rs
@@ -13,15 +13,17 @@ use rustc_span::symbol::sym;
 use rustc_span::Span;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for private functions that only return `Ok` or `Some`.
+    /// ### What it does
+    /// Checks for private functions that only return `Ok` or `Some`.
     ///
-    /// **Why is this bad?** It is not meaningful to wrap values when no `None` or `Err` is returned.
+    /// ### Why is this bad?
+    /// It is not meaningful to wrap values when no `None` or `Err` is returned.
     ///
-    /// **Known problems:** There can be false positives if the function signature is designed to
+    /// ### Known problems
+    /// There can be false positives if the function signature is designed to
     /// fit some external requirement.
     ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust
     /// fn get_cool_number(a: bool, b: bool) -> Option<i32> {
     ///     if a && b {
diff --git a/clippy_lints/src/unnested_or_patterns.rs b/clippy_lints/src/unnested_or_patterns.rs
index 07a4e29404979..9acfbc994b382 100644
--- a/clippy_lints/src/unnested_or_patterns.rs
+++ b/clippy_lints/src/unnested_or_patterns.rs
@@ -17,22 +17,17 @@ use std::cell::Cell;
 use std::mem;
 
 declare_clippy_lint! {
-    /// **What it does:**
-    ///
+    /// ### What it does
     /// Checks for unnested or-patterns, e.g., `Some(0) | Some(2)` and
     /// suggests replacing the pattern with a nested one, `Some(0 | 2)`.
     ///
     /// Another way to think of this is that it rewrites patterns in
     /// *disjunctive normal form (DNF)* into *conjunctive normal form (CNF)*.
     ///
-    /// **Why is this bad?**
-    ///
+    /// ### Why is this bad?
     /// In the example above, `Some` is repeated, which unncessarily complicates the pattern.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust
     /// fn main() {
     ///     if let Some(0) | Some(2) = Some(0) {}
diff --git a/clippy_lints/src/unsafe_removed_from_name.rs b/clippy_lints/src/unsafe_removed_from_name.rs
index 16ad9d2dfd32c..3c694af2b9dee 100644
--- a/clippy_lints/src/unsafe_removed_from_name.rs
+++ b/clippy_lints/src/unsafe_removed_from_name.rs
@@ -6,15 +6,15 @@ use rustc_span::source_map::Span;
 use rustc_span::symbol::Ident;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for imports that remove "unsafe" from an item's
+    /// ### What it does
+    /// Checks for imports that remove "unsafe" from an item's
     /// name.
     ///
-    /// **Why is this bad?** Renaming makes it less clear which traits and
+    /// ### Why is this bad?
+    /// Renaming makes it less clear which traits and
     /// structures are unsafe.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust,ignore
     /// use std::cell::{UnsafeCell as TotallySafeCell};
     ///
diff --git a/clippy_lints/src/unused_async.rs b/clippy_lints/src/unused_async.rs
index 18ee07d3a9587..3a6a07c522630 100644
--- a/clippy_lints/src/unused_async.rs
+++ b/clippy_lints/src/unused_async.rs
@@ -7,16 +7,15 @@ use rustc_session::{declare_lint_pass, declare_tool_lint};
 use rustc_span::Span;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for functions that are declared `async` but have no `.await`s inside of them.
+    /// ### What it does
+    /// Checks for functions that are declared `async` but have no `.await`s inside of them.
     ///
-    /// **Why is this bad?** Async functions with no async code create overhead, both mentally and computationally.
+    /// ### Why is this bad?
+    /// Async functions with no async code create overhead, both mentally and computationally.
     /// Callers of async methods either need to be calling from an async function themselves or run it on an executor, both of which
     /// causes runtime overhead and hassle for the caller.
     ///
-    /// **Known problems:** None
-    ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust
     /// // Bad
     /// async fn get_random_number() -> i64 {
diff --git a/clippy_lints/src/unused_io_amount.rs b/clippy_lints/src/unused_io_amount.rs
index ee082d30d936b..82bc4a6d15343 100644
--- a/clippy_lints/src/unused_io_amount.rs
+++ b/clippy_lints/src/unused_io_amount.rs
@@ -5,9 +5,11 @@ use rustc_lint::{LateContext, LateLintPass};
 use rustc_session::{declare_lint_pass, declare_tool_lint};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for unused written/read amount.
+    /// ### What it does
+    /// Checks for unused written/read amount.
     ///
-    /// **Why is this bad?** `io::Write::write(_vectored)` and
+    /// ### Why is this bad?
+    /// `io::Write::write(_vectored)` and
     /// `io::Read::read(_vectored)` are not guaranteed to
     /// process the entire buffer. They return how many bytes were processed, which
     /// might be smaller
@@ -15,9 +17,10 @@ declare_clippy_lint! {
     /// partial-write/read, use
     /// `write_all`/`read_exact` instead.
     ///
-    /// **Known problems:** Detects only common patterns.
+    /// ### Known problems
+    /// Detects only common patterns.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust,ignore
     /// use std::io;
     /// fn foo<W: io::Write>(w: &mut W) -> io::Result<()> {
diff --git a/clippy_lints/src/unused_self.rs b/clippy_lints/src/unused_self.rs
index 15343cf90f231..658ac81f6eac8 100644
--- a/clippy_lints/src/unused_self.rs
+++ b/clippy_lints/src/unused_self.rs
@@ -6,14 +6,14 @@ use rustc_lint::{LateContext, LateLintPass};
 use rustc_session::{declare_lint_pass, declare_tool_lint};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks methods that contain a `self` argument but don't use it
+    /// ### What it does
+    /// Checks methods that contain a `self` argument but don't use it
     ///
-    /// **Why is this bad?** It may be clearer to define the method as an associated function instead
+    /// ### Why is this bad?
+    /// It may be clearer to define the method as an associated function instead
     /// of an instance method if it doesn't require `self`.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust,ignore
     /// struct A;
     /// impl A {
diff --git a/clippy_lints/src/unused_unit.rs b/clippy_lints/src/unused_unit.rs
index ab0cdf75ffe0a..9ed5e585f841d 100644
--- a/clippy_lints/src/unused_unit.rs
+++ b/clippy_lints/src/unused_unit.rs
@@ -10,15 +10,15 @@ use rustc_span::source_map::Span;
 use rustc_span::BytePos;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for unit (`()`) expressions that can be removed.
+    /// ### What it does
+    /// Checks for unit (`()`) expressions that can be removed.
     ///
-    /// **Why is this bad?** Such expressions add no value, but can make the code
+    /// ### Why is this bad?
+    /// Such expressions add no value, but can make the code
     /// less readable. Depending on formatting they can make a `break` or `return`
     /// statement look like a function call.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// fn return_unit() -> () {
     ///     ()
diff --git a/clippy_lints/src/unwrap.rs b/clippy_lints/src/unwrap.rs
index d4efee56efff5..c5b8acb9982d8 100644
--- a/clippy_lints/src/unwrap.rs
+++ b/clippy_lints/src/unwrap.rs
@@ -13,13 +13,13 @@ use rustc_span::source_map::Span;
 use rustc_span::sym;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for calls of `unwrap[_err]()` that cannot fail.
+    /// ### What it does
+    /// Checks for calls of `unwrap[_err]()` that cannot fail.
     ///
-    /// **Why is this bad?** Using `if let` or `match` is more idiomatic.
+    /// ### Why is this bad?
+    /// Using `if let` or `match` is more idiomatic.
     ///
-    /// **Known problems:** None
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # let option = Some(0);
     /// # fn do_something_with(_x: usize) {}
@@ -43,14 +43,17 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for calls of `unwrap[_err]()` that will always fail.
+    /// ### What it does
+    /// Checks for calls of `unwrap[_err]()` that will always fail.
     ///
-    /// **Why is this bad?** If panicking is desired, an explicit `panic!()` should be used.
+    /// ### Why is this bad?
+    /// If panicking is desired, an explicit `panic!()` should be used.
     ///
-    /// **Known problems:** This lint only checks `if` conditions not assignments.
+    /// ### Known problems
+    /// This lint only checks `if` conditions not assignments.
     /// So something like `let x: Option<()> = None; x.unwrap();` will not be recognized.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # let option = Some(0);
     /// # fn do_something_with(_x: usize) {}
diff --git a/clippy_lints/src/unwrap_in_result.rs b/clippy_lints/src/unwrap_in_result.rs
index d17aa6d842411..6eadd1fc1c933 100644
--- a/clippy_lints/src/unwrap_in_result.rs
+++ b/clippy_lints/src/unwrap_in_result.rs
@@ -12,13 +12,16 @@ use rustc_session::{declare_lint_pass, declare_tool_lint};
 use rustc_span::{sym, Span};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for functions of type Result that contain `expect()` or `unwrap()`
+    /// ### What it does
+    /// Checks for functions of type Result that contain `expect()` or `unwrap()`
     ///
-    /// **Why is this bad?** These functions promote recoverable errors to non-recoverable errors which may be undesirable in code bases which wish to avoid panics.
+    /// ### Why is this bad?
+    /// These functions promote recoverable errors to non-recoverable errors which may be undesirable in code bases which wish to avoid panics.
     ///
-    /// **Known problems:** This can cause false positives in functions that handle both recoverable and non recoverable errors.
+    /// ### Known problems
+    /// This can cause false positives in functions that handle both recoverable and non recoverable errors.
     ///
-    /// **Example:**
+    /// ### Example
     /// Before:
     /// ```rust
     /// fn divisible_by_3(i_str: String) -> Result<(), String> {
diff --git a/clippy_lints/src/upper_case_acronyms.rs b/clippy_lints/src/upper_case_acronyms.rs
index 0b58c6c0917ca..7fa0e23ee73ea 100644
--- a/clippy_lints/src/upper_case_acronyms.rs
+++ b/clippy_lints/src/upper_case_acronyms.rs
@@ -8,9 +8,11 @@ use rustc_session::{declare_tool_lint, impl_lint_pass};
 use rustc_span::symbol::Ident;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for fully capitalized names and optionally names containing a capitalized acronym.
+    /// ### What it does
+    /// Checks for fully capitalized names and optionally names containing a capitalized acronym.
     ///
-    /// **Why is this bad?** In CamelCase, acronyms count as one word.
+    /// ### Why is this bad?
+    /// In CamelCase, acronyms count as one word.
     /// See [naming conventions](https://rust-lang.github.io/api-guidelines/naming.html#casing-conforms-to-rfc-430-c-case)
     /// for more.
     ///
@@ -18,12 +20,12 @@ declare_clippy_lint! {
     /// You can use the `upper-case-acronyms-aggressive: true` config option to enable linting
     /// on all camel case names
     ///
-    /// **Known problems:** When two acronyms are contiguous, the lint can't tell where
+    /// ### Known problems
+    /// When two acronyms are contiguous, the lint can't tell where
     /// the first acronym ends and the second starts, so it suggests to lowercase all of
     /// the letters in the second acronym.
     ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust
     /// struct HTTPResponse;
     /// ```
diff --git a/clippy_lints/src/use_self.rs b/clippy_lints/src/use_self.rs
index 71117e967e319..fbd552186df86 100644
--- a/clippy_lints/src/use_self.rs
+++ b/clippy_lints/src/use_self.rs
@@ -20,19 +20,20 @@ use rustc_span::Span;
 use rustc_typeck::hir_ty_to_ty;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for unnecessary repetition of structure name when a
+    /// ### What it does
+    /// Checks for unnecessary repetition of structure name when a
     /// replacement with `Self` is applicable.
     ///
-    /// **Why is this bad?** Unnecessary repetition. Mixed use of `Self` and struct
+    /// ### Why is this bad?
+    /// Unnecessary repetition. Mixed use of `Self` and struct
     /// name
     /// feels inconsistent.
     ///
-    /// **Known problems:**
+    /// ### Known problems
     /// - Unaddressed false negative in fn bodies of trait implementations
     /// - False positive with assotiated types in traits (#4140)
     ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust
     /// struct Foo {}
     /// impl Foo {
diff --git a/clippy_lints/src/useless_conversion.rs b/clippy_lints/src/useless_conversion.rs
index 25a959d3e416c..2861b43291901 100644
--- a/clippy_lints/src/useless_conversion.rs
+++ b/clippy_lints/src/useless_conversion.rs
@@ -12,15 +12,14 @@ use rustc_session::{declare_tool_lint, impl_lint_pass};
 use rustc_span::sym;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for `Into`, `TryInto`, `From`, `TryFrom`, or `IntoIter` calls
+    /// ### What it does
+    /// Checks for `Into`, `TryInto`, `From`, `TryFrom`, or `IntoIter` calls
     /// which uselessly convert to the same type.
     ///
-    /// **Why is this bad?** Redundant code.
-    ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Why is this bad?
+    /// Redundant code.
     ///
+    /// ### Example
     /// ```rust
     /// // Bad
     /// // format!() returns a `String`
diff --git a/clippy_lints/src/utils/author.rs b/clippy_lints/src/utils/author.rs
index c1e7fd7fe9578..61fd375a9892c 100644
--- a/clippy_lints/src/utils/author.rs
+++ b/clippy_lints/src/utils/author.rs
@@ -13,9 +13,10 @@ use rustc_middle::hir::map::Map;
 use rustc_session::{declare_lint_pass, declare_tool_lint};
 
 declare_clippy_lint! {
-    /// **What it does:** Generates clippy code that detects the offending pattern
+    /// ### What it does
+    /// Generates clippy code that detects the offending pattern
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust,ignore
     /// // ./tests/ui/my_lint.rs
     /// fn foo() {
diff --git a/clippy_lints/src/utils/inspector.rs b/clippy_lints/src/utils/inspector.rs
index 4665eeeff7b21..f7ddee12dcf64 100644
--- a/clippy_lints/src/utils/inspector.rs
+++ b/clippy_lints/src/utils/inspector.rs
@@ -8,10 +8,11 @@ use rustc_session::Session;
 use rustc_session::{declare_lint_pass, declare_tool_lint};
 
 declare_clippy_lint! {
-    /// **What it does:** Dumps every ast/hir node which has the `#[clippy::dump]`
+    /// ### What it does
+    /// Dumps every ast/hir node which has the `#[clippy::dump]`
     /// attribute
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust,ignore
     /// #[clippy::dump]
     /// extern crate foo;
diff --git a/clippy_lints/src/utils/internal_lints.rs b/clippy_lints/src/utils/internal_lints.rs
index 668807f499f3f..d660008e7d184 100644
--- a/clippy_lints/src/utils/internal_lints.rs
+++ b/clippy_lints/src/utils/internal_lints.rs
@@ -36,29 +36,33 @@ use std::borrow::{Borrow, Cow};
 pub mod metadata_collector;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for various things we like to keep tidy in clippy.
+    /// ### What it does
+    /// Checks for various things we like to keep tidy in clippy.
     ///
-    /// **Why is this bad?** We like to pretend we're an example of tidy code.
+    /// ### Why is this bad?
+    /// We like to pretend we're an example of tidy code.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:** Wrong ordering of the util::paths constants.
+    /// ### Example
+    /// Wrong ordering of the util::paths constants.
     pub CLIPPY_LINTS_INTERNAL,
     internal,
     "various things that will negatively affect your clippy experience"
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Ensures every lint is associated to a `LintPass`.
+    /// ### What it does
+    /// Ensures every lint is associated to a `LintPass`.
     ///
-    /// **Why is this bad?** The compiler only knows lints via a `LintPass`. Without
+    /// ### Why is this bad?
+    /// The compiler only knows lints via a `LintPass`. Without
     /// putting a lint to a `LintPass::get_lints()`'s return, the compiler will not
     /// know the name of the lint.
     ///
-    /// **Known problems:** Only checks for lints associated using the
+    /// ### Known problems
+    /// Only checks for lints associated using the
     /// `declare_lint_pass!`, `impl_lint_pass!`, and `lint_array!` macros.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust,ignore
     /// declare_lint! { pub LINT_1, ... }
     /// declare_lint! { pub LINT_2, ... }
@@ -73,15 +77,15 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for calls to `cx.span_lint*` and suggests to use the `utils::*`
+    /// ### What it does
+    /// Checks for calls to `cx.span_lint*` and suggests to use the `utils::*`
     /// variant of the function.
     ///
-    /// **Why is this bad?** The `utils::*` variants also add a link to the Clippy documentation to the
+    /// ### Why is this bad?
+    /// The `utils::*` variants also add a link to the Clippy documentation to the
     /// warning/error messages.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// Bad:
     /// ```rust,ignore
     /// cx.span_lint(LINT_NAME, "message");
@@ -97,14 +101,14 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for calls to `cx.outer().expn_data()` and suggests to use
+    /// ### What it does
+    /// Checks for calls to `cx.outer().expn_data()` and suggests to use
     /// the `cx.outer_expn_data()`
     ///
-    /// **Why is this bad?** `cx.outer_expn_data()` is faster and more concise.
-    ///
-    /// **Known problems:** None.
+    /// ### Why is this bad?
+    /// `cx.outer_expn_data()` is faster and more concise.
     ///
-    /// **Example:**
+    /// ### Example
     /// Bad:
     /// ```rust,ignore
     /// expr.span.ctxt().outer().expn_data()
@@ -120,14 +124,14 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Not an actual lint. This lint is only meant for testing our customized internal compiler
+    /// ### What it does
+    /// Not an actual lint. This lint is only meant for testing our customized internal compiler
     /// error message by calling `panic`.
     ///
-    /// **Why is this bad?** ICE in large quantities can damage your teeth
+    /// ### Why is this bad?
+    /// ICE in large quantities can damage your teeth
     ///
-    /// **Known problems:** None
-    ///
-    /// **Example:**
+    /// ### Example
     /// Bad:
     /// ```rust,ignore
     /// 🍦🍦🍦🍦🍦
@@ -138,14 +142,14 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for cases of an auto-generated lint without an updated description,
+    /// ### What it does
+    /// Checks for cases of an auto-generated lint without an updated description,
     /// i.e. `default lint description`.
     ///
-    /// **Why is this bad?** Indicates that the lint is not finished.
-    ///
-    /// **Known problems:** None
+    /// ### Why is this bad?
+    /// Indicates that the lint is not finished.
     ///
-    /// **Example:**
+    /// ### Example
     /// Bad:
     /// ```rust,ignore
     /// declare_lint! { pub COOL_LINT, nursery, "default lint description" }
@@ -161,7 +165,8 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Lints `span_lint_and_then` function calls, where the
+    /// ### What it does
+    /// Lints `span_lint_and_then` function calls, where the
     /// closure argument has only one statement and that statement is a method
     /// call to `span_suggestion`, `span_help`, `span_note` (using the same
     /// span), `help` or `note`.
@@ -170,12 +175,11 @@ declare_clippy_lint! {
     /// wrapper functions `span_lint_and_sugg`, span_lint_and_help`, or
     /// `span_lint_and_note`.
     ///
-    /// **Why is this bad?** Using the wrapper `span_lint_and_*` functions, is more
+    /// ### Why is this bad?
+    /// Using the wrapper `span_lint_and_*` functions, is more
     /// convenient, readable and less error prone.
     ///
-    /// **Known problems:** None
-    ///
-    /// *Example:**
+    /// ### Example
     /// Bad:
     /// ```rust,ignore
     /// span_lint_and_then(cx, TEST_LINT, expr.span, lint_msg, |diag| {
@@ -222,14 +226,14 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for calls to `utils::match_type()` on a type diagnostic item
+    /// ### What it does
+    /// Checks for calls to `utils::match_type()` on a type diagnostic item
     /// and suggests to use `utils::is_type_diagnostic_item()` instead.
     ///
-    /// **Why is this bad?** `utils::is_type_diagnostic_item()` does not require hardcoded paths.
-    ///
-    /// **Known problems:** None.
+    /// ### Why is this bad?
+    /// `utils::is_type_diagnostic_item()` does not require hardcoded paths.
     ///
-    /// **Example:**
+    /// ### Example
     /// Bad:
     /// ```rust,ignore
     /// utils::match_type(cx, ty, &paths::VEC)
@@ -245,30 +249,27 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:**
+    /// ### What it does
     /// Checks the paths module for invalid paths.
     ///
-    /// **Why is this bad?**
+    /// ### Why is this bad?
     /// It indicates a bug in the code.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:** None.
+    /// ### Example
+    /// None.
     pub INVALID_PATHS,
     internal,
     "invalid path"
 }
 
 declare_clippy_lint! {
-    /// **What it does:**
+    /// ### What it does
     /// Checks for interning symbols that have already been pre-interned and defined as constants.
     ///
-    /// **Why is this bad?**
+    /// ### Why is this bad?
     /// It's faster and easier to use the symbol constant.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// Bad:
     /// ```rust,ignore
     /// let _ = sym!(f32);
@@ -284,13 +285,13 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for unnecessary conversion from Symbol to a string.
-    ///
-    /// **Why is this bad?** It's faster use symbols directly intead of strings.
+    /// ### What it does
+    /// Checks for unnecessary conversion from Symbol to a string.
     ///
-    /// **Known problems:** None.
+    /// ### Why is this bad?
+    /// It's faster use symbols directly intead of strings.
     ///
-    /// **Example:**
+    /// ### Example
     /// Bad:
     /// ```rust,ignore
     /// symbol.as_str() == "clippy";
diff --git a/clippy_lints/src/utils/internal_lints/metadata_collector.rs b/clippy_lints/src/utils/internal_lints/metadata_collector.rs
index 4a6861bd9365a..47336459d7da6 100644
--- a/clippy_lints/src/utils/internal_lints/metadata_collector.rs
+++ b/clippy_lints/src/utils/internal_lints/metadata_collector.rs
@@ -68,7 +68,7 @@ const CLIPPY_LINT_GROUP_PREFIX: &str = "clippy::";
 macro_rules! CONFIGURATION_SECTION_TEMPLATE {
     () => {
         r#"
-**Configuration**
+### Configuration
 This lint has the following configuration variables:
 
 {configurations}
@@ -118,18 +118,21 @@ const APPLICABILITY_NAME_INDEX: usize = 2;
 const APPLICABILITY_UNRESOLVED_STR: &str = "Unresolved";
 
 declare_clippy_lint! {
-    /// **What it does:** Collects metadata about clippy lints for the website.
+    /// ### What it does
+    /// Collects metadata about clippy lints for the website.
     ///
     /// This lint will be used to report problems of syntax parsing. You should hopefully never
     /// see this but never say never I guess ^^
     ///
-    /// **Why is this bad?** This is not a bad thing but definitely a hacky way to do it. See
+    /// ### Why is this bad?
+    /// This is not a bad thing but definitely a hacky way to do it. See
     /// issue [#4310](https://github.com/rust-lang/rust-clippy/issues/4310) for a discussion
     /// about the implementation.
     ///
-    /// **Known problems:** Hopefully none. It would be pretty uncool to have a problem here :)
+    /// ### Known problems
+    /// Hopefully none. It would be pretty uncool to have a problem here :)
     ///
-    /// **Example output:**
+    /// ### Example output
     /// ```json,ignore
     /// {
     ///     "id": "internal_metadata_collector",
@@ -138,7 +141,7 @@ declare_clippy_lint! {
     ///         "line": 1
     ///     },
     ///     "group": "clippy::internal",
-    ///     "docs": " **What it does:** Collects metadata about clippy lints for the website. [...] "
+    ///     "docs": " ### What it does\nCollects metadata about clippy lints for the website. [...] "
     /// }
     /// ```
     pub INTERNAL_METADATA_COLLECTOR,
@@ -378,7 +381,8 @@ impl<'hir> LateLintPass<'hir> for MetadataCollector {
     /// Collecting lint declarations like:
     /// ```rust, ignore
     /// declare_clippy_lint! {
-    ///     /// **What it does:** Something IDK.
+    ///     /// ### What it does
+    ///     /// Something IDK.
     ///     pub SOME_LINT,
     ///     internal,
     ///     "Who am I?"
diff --git a/clippy_lints/src/vec.rs b/clippy_lints/src/vec.rs
index 1d5b7c98d3141..32fa46f042ce1 100644
--- a/clippy_lints/src/vec.rs
+++ b/clippy_lints/src/vec.rs
@@ -19,14 +19,14 @@ pub struct UselessVec {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for usage of `&vec![..]` when using `&[..]` would
+    /// ### What it does
+    /// Checks for usage of `&vec![..]` when using `&[..]` would
     /// be possible.
     ///
-    /// **Why is this bad?** This is less efficient.
+    /// ### Why is this bad?
+    /// This is less efficient.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # fn foo(my_vec: &[u8]) {}
     ///
diff --git a/clippy_lints/src/vec_init_then_push.rs b/clippy_lints/src/vec_init_then_push.rs
index c7190e2f9798c..0413c02b230e5 100644
--- a/clippy_lints/src/vec_init_then_push.rs
+++ b/clippy_lints/src/vec_init_then_push.rs
@@ -13,15 +13,14 @@ use rustc_span::{symbol::sym, Span};
 use std::convert::TryInto;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for calls to `push` immediately after creating a new `Vec`.
+    /// ### What it does
+    /// Checks for calls to `push` immediately after creating a new `Vec`.
     ///
-    /// **Why is this bad?** The `vec![]` macro is both more performant and easier to read than
+    /// ### Why is this bad?
+    /// The `vec![]` macro is both more performant and easier to read than
     /// multiple `push` calls.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust
     /// let mut v = Vec::new();
     /// v.push(0);
diff --git a/clippy_lints/src/vec_resize_to_zero.rs b/clippy_lints/src/vec_resize_to_zero.rs
index 5540e87405ff9..5c0429db6b8df 100644
--- a/clippy_lints/src/vec_resize_to_zero.rs
+++ b/clippy_lints/src/vec_resize_to_zero.rs
@@ -10,13 +10,13 @@ use rustc_session::{declare_lint_pass, declare_tool_lint};
 use rustc_span::source_map::Spanned;
 
 declare_clippy_lint! {
-    /// **What it does:** Finds occurrences of `Vec::resize(0, an_int)`
+    /// ### What it does
+    /// Finds occurrences of `Vec::resize(0, an_int)`
     ///
-    /// **Why is this bad?** This is probably an argument inversion mistake.
+    /// ### Why is this bad?
+    /// This is probably an argument inversion mistake.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// vec!(1, 2, 3, 4, 5).resize(0, 5)
     /// ```
diff --git a/clippy_lints/src/verbose_file_reads.rs b/clippy_lints/src/verbose_file_reads.rs
index 3ab68df2b6d7c..e07c12f4f1615 100644
--- a/clippy_lints/src/verbose_file_reads.rs
+++ b/clippy_lints/src/verbose_file_reads.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 use of File::read_to_end and File::read_to_string.
+    /// ### What it does
+    /// Checks for use of File::read_to_end and File::read_to_string.
     ///
-    /// **Why is this bad?** `fs::{read, read_to_string}` provide the same functionality when `buf` is empty with fewer imports and no intermediate values.
+    /// ### Why is this bad?
+    /// `fs::{read, read_to_string}` provide the same functionality when `buf` is empty with fewer imports and no intermediate values.
     /// See also: [fs::read docs](https://doc.rust-lang.org/std/fs/fn.read.html), [fs::read_to_string docs](https://doc.rust-lang.org/std/fs/fn.read_to_string.html)
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust,no_run
     /// # use std::io::Read;
     /// # use std::fs::File;
diff --git a/clippy_lints/src/wildcard_dependencies.rs b/clippy_lints/src/wildcard_dependencies.rs
index 1ca1117a41ea5..fd3872bacbe24 100644
--- a/clippy_lints/src/wildcard_dependencies.rs
+++ b/clippy_lints/src/wildcard_dependencies.rs
@@ -7,16 +7,15 @@ use rustc_span::source_map::DUMMY_SP;
 use if_chain::if_chain;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for wildcard dependencies in the `Cargo.toml`.
+    /// ### What it does
+    /// Checks for wildcard dependencies in the `Cargo.toml`.
     ///
-    /// **Why is this bad?** [As the edition guide says](https://rust-lang-nursery.github.io/edition-guide/rust-2018/cargo-and-crates-io/crates-io-disallows-wildcard-dependencies.html),
+    /// ### Why is this bad?
+    /// [As the edition guide says](https://rust-lang-nursery.github.io/edition-guide/rust-2018/cargo-and-crates-io/crates-io-disallows-wildcard-dependencies.html),
     /// it is highly unlikely that you work with any possible version of your dependency,
     /// and wildcard dependencies would cause unnecessary breakage in the ecosystem.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```toml
     /// [dependencies]
     /// regex = "*"
diff --git a/clippy_lints/src/wildcard_imports.rs b/clippy_lints/src/wildcard_imports.rs
index 520586b3a1f42..bafb9d3e3b16a 100644
--- a/clippy_lints/src/wildcard_imports.rs
+++ b/clippy_lints/src/wildcard_imports.rs
@@ -13,15 +13,18 @@ use rustc_span::symbol::kw;
 use rustc_span::{sym, BytePos};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for `use Enum::*`.
+    /// ### What it does
+    /// Checks for `use Enum::*`.
     ///
-    /// **Why is this bad?** It is usually better style to use the prefixed name of
+    /// ### Why is this bad?
+    /// It is usually better style to use the prefixed name of
     /// an enumeration variant, rather than importing variants.
     ///
-    /// **Known problems:** Old-style enumerations that prefix the variants are
+    /// ### Known problems
+    /// Old-style enumerations that prefix the variants are
     /// still around.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust,ignore
     /// // Bad
     /// use std::cmp::Ordering::*;
@@ -37,9 +40,11 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for wildcard imports `use _::*`.
+    /// ### What it does
+    /// Checks for wildcard imports `use _::*`.
     ///
-    /// **Why is this bad?** wildcard imports can pollute the namespace. This is especially bad if
+    /// ### Why is this bad?
+    /// wildcard imports can pollute the namespace. This is especially bad if
     /// you try to import something through a wildcard, that already has been imported by name from
     /// a different source:
     ///
@@ -52,8 +57,7 @@ declare_clippy_lint! {
     ///
     /// This can lead to confusing error messages at best and to unexpected behavior at worst.
     ///
-    /// **Exceptions:**
-    ///
+    /// ### Exceptions
     /// Wildcard imports are allowed from modules named `prelude`. Many crates (including the standard library)
     /// provide modules named "prelude" specifically designed for wildcard import.
     ///
@@ -61,14 +65,14 @@ declare_clippy_lint! {
     ///
     /// These exceptions can be disabled using the `warn-on-all-wildcard-imports` configuration flag.
     ///
-    /// **Known problems:** If macros are imported through the wildcard, this macro is not included
+    /// ### Known problems
+    /// If macros are imported through the wildcard, this macro is not included
     /// by the suggestion and has to be added by hand.
     ///
     /// Applying the suggestion when explicit imports of the things imported with a glob import
     /// exist, may result in `unused_imports` warnings.
     ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust,ignore
     /// // Bad
     /// use crate1::*;
diff --git a/clippy_lints/src/write.rs b/clippy_lints/src/write.rs
index 5229a7058659c..4553ac704a28f 100644
--- a/clippy_lints/src/write.rs
+++ b/clippy_lints/src/write.rs
@@ -16,14 +16,14 @@ use rustc_span::symbol::{kw, Symbol};
 use rustc_span::{sym, BytePos, Span, DUMMY_SP};
 
 declare_clippy_lint! {
-    /// **What it does:** This lint warns when you use `println!("")` to
+    /// ### What it does
+    /// This lint warns when you use `println!("")` to
     /// print a newline.
     ///
-    /// **Why is this bad?** You should use `println!()`, which is simpler.
+    /// ### Why is this bad?
+    /// You should use `println!()`, which is simpler.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// // Bad
     /// println!("");
@@ -37,15 +37,15 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** This lint warns when you use `print!()` with a format
+    /// ### What it does
+    /// This lint warns when you use `print!()` with a format
     /// string that ends in a newline.
     ///
-    /// **Why is this bad?** You should use `println!()` instead, which appends the
+    /// ### Why is this bad?
+    /// You should use `println!()` instead, which appends the
     /// newline.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # let name = "World";
     /// print!("Hello {}!\n", name);
@@ -61,15 +61,18 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for printing on *stdout*. The purpose of this lint
+    /// ### What it does
+    /// Checks for printing on *stdout*. The purpose of this lint
     /// is to catch debugging remnants.
     ///
-    /// **Why is this bad?** People often print on *stdout* while debugging an
+    /// ### Why is this bad?
+    /// People often print on *stdout* while debugging an
     /// application and might forget to remove those prints afterward.
     ///
-    /// **Known problems:** Only catches `print!` and `println!` calls.
+    /// ### Known problems
+    /// Only catches `print!` and `println!` calls.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// println!("Hello world!");
     /// ```
@@ -79,15 +82,18 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for printing on *stderr*. The purpose of this lint
+    /// ### What it does
+    /// Checks for printing on *stderr*. The purpose of this lint
     /// is to catch debugging remnants.
     ///
-    /// **Why is this bad?** People often print on *stderr* while debugging an
+    /// ### Why is this bad?
+    /// People often print on *stderr* while debugging an
     /// application and might forget to remove those prints afterward.
     ///
-    /// **Known problems:** Only catches `eprint!` and `eprintln!` calls.
+    /// ### Known problems
+    /// Only catches `eprint!` and `eprintln!` calls.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// eprintln!("Hello world!");
     /// ```
@@ -97,13 +103,15 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for use of `Debug` formatting. The purpose of this
+    /// ### What it does
+    /// Checks for use of `Debug` formatting. The purpose of this
     /// lint is to catch debugging remnants.
     ///
-    /// **Why is this bad?** The purpose of the `Debug` trait is to facilitate
+    /// ### Why is this bad?
+    /// The purpose of the `Debug` trait is to facilitate
     /// debugging Rust code. It should not be used in user-facing output.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # let foo = "bar";
     /// println!("{:?}", foo);
@@ -114,16 +122,19 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** This lint warns about the use of literals as `print!`/`println!` args.
+    /// ### What it does
+    /// This lint warns about the use of literals as `print!`/`println!` args.
     ///
-    /// **Why is this bad?** Using literals as `println!` args is inefficient
+    /// ### Why is this bad?
+    /// Using literals as `println!` args is inefficient
     /// (c.f., https://github.com/matthiaskrgr/rust-str-bench) and unnecessary
     /// (i.e., just put the literal in the format string)
     ///
-    /// **Known problems:** Will also warn with macro calls as arguments that expand to literals
+    /// ### Known problems
+    /// Will also warn with macro calls as arguments that expand to literals
     /// -- e.g., `println!("{}", env!("FOO"))`.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// println!("{}", "foo");
     /// ```
@@ -137,14 +148,14 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** This lint warns when you use `writeln!(buf, "")` to
+    /// ### What it does
+    /// This lint warns when you use `writeln!(buf, "")` to
     /// print a newline.
     ///
-    /// **Why is this bad?** You should use `writeln!(buf)`, which is simpler.
+    /// ### Why is this bad?
+    /// You should use `writeln!(buf)`, which is simpler.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # use std::fmt::Write;
     /// # let mut buf = String::new();
@@ -160,16 +171,16 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** This lint warns when you use `write!()` with a format
+    /// ### What it does
+    /// This lint warns when you use `write!()` with a format
     /// string that
     /// ends in a newline.
     ///
-    /// **Why is this bad?** You should use `writeln!()` instead, which appends the
+    /// ### Why is this bad?
+    /// You should use `writeln!()` instead, which appends the
     /// newline.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # use std::fmt::Write;
     /// # let mut buf = String::new();
@@ -186,16 +197,19 @@ declare_clippy_lint! {
 }
 
 declare_clippy_lint! {
-    /// **What it does:** This lint warns about the use of literals as `write!`/`writeln!` args.
+    /// ### What it does
+    /// This lint warns about the use of literals as `write!`/`writeln!` args.
     ///
-    /// **Why is this bad?** Using literals as `writeln!` args is inefficient
+    /// ### Why is this bad?
+    /// Using literals as `writeln!` args is inefficient
     /// (c.f., https://github.com/matthiaskrgr/rust-str-bench) and unnecessary
     /// (i.e., just put the literal in the format string)
     ///
-    /// **Known problems:** Will also warn with macro calls as arguments that expand to literals
+    /// ### Known problems
+    /// Will also warn with macro calls as arguments that expand to literals
     /// -- e.g., `writeln!(buf, "{}", env!("FOO"))`.
     ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// # use std::fmt::Write;
     /// # let mut buf = String::new();
diff --git a/clippy_lints/src/zero_div_zero.rs b/clippy_lints/src/zero_div_zero.rs
index a1ea743ba804d..b29ced28ac491 100644
--- a/clippy_lints/src/zero_div_zero.rs
+++ b/clippy_lints/src/zero_div_zero.rs
@@ -6,13 +6,13 @@ use rustc_lint::{LateContext, LateLintPass};
 use rustc_session::{declare_lint_pass, declare_tool_lint};
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for `0.0 / 0.0`.
+    /// ### What it does
+    /// Checks for `0.0 / 0.0`.
     ///
-    /// **Why is this bad?** It's less readable than `f32::NAN` or `f64::NAN`.
+    /// ### Why is this bad?
+    /// It's less readable than `f32::NAN` or `f64::NAN`.
     ///
-    /// **Known problems:** None.
-    ///
-    /// **Example:**
+    /// ### Example
     /// ```rust
     /// // Bad
     /// let nan = 0.0f32 / 0.0;
diff --git a/clippy_lints/src/zero_sized_map_values.rs b/clippy_lints/src/zero_sized_map_values.rs
index d6a8112218f13..2fbe27f94798b 100644
--- a/clippy_lints/src/zero_sized_map_values.rs
+++ b/clippy_lints/src/zero_sized_map_values.rs
@@ -10,18 +10,19 @@ use rustc_target::abi::LayoutOf as _;
 use rustc_typeck::hir_ty_to_ty;
 
 declare_clippy_lint! {
-    /// **What it does:** Checks for maps with zero-sized value types anywhere in the code.
+    /// ### What it does
+    /// Checks for maps with zero-sized value types anywhere in the code.
     ///
-    /// **Why is this bad?** Since there is only a single value for a zero-sized type, a map
+    /// ### Why is this bad?
+    /// Since there is only a single value for a zero-sized type, a map
     /// containing zero sized values is effectively a set. Using a set in that case improves
     /// readability and communicates intent more clearly.
     ///
-    /// **Known problems:**
+    /// ### Known problems
     /// * A zero-sized type cannot be recovered later if it contains private fields.
     /// * This lints the signature of public items
     ///
-    /// **Example:**
-    ///
+    /// ### Example
     /// ```rust
     /// # use std::collections::HashMap;
     /// fn unique_words(text: &str) -> HashMap<&str, ()> {
diff --git a/doc/adding_lints.md b/doc/adding_lints.md
index 5a06afedbf4c2..f2260c3d1a267 100644
--- a/doc/adding_lints.md
+++ b/doc/adding_lints.md
@@ -11,6 +11,7 @@ because that's clearly a non-descriptive name.
   - [Setup](#setup)
   - [Getting Started](#getting-started)
   - [Testing](#testing)
+    - [Cargo lints](#cargo-lints)
   - [Rustfix tests](#rustfix-tests)
   - [Edition 2018 tests](#edition-2018-tests)
   - [Testing manually](#testing-manually)
@@ -179,14 +180,11 @@ the auto-generated lint declaration to have a real description, something like t
 
 ```rust
 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
     /// ```
@@ -487,13 +485,13 @@ Please document your lint with a doc comment akin to the following:
 
 ```rust
 declare_clippy_lint! {
-    /// **What it does:** Checks for ... (describe what the lint matches).
-    ///
-    /// **Why is this bad?** Supply the reason for linting the code.
+    /// ### What it does
+    /// Checks for ... (describe what the lint matches).
     ///
-    /// **Known problems:** None. (Or describe where it could go wrong.)
+    /// ### Why is this bad?
+    /// Supply the reason for linting the code.
     ///
-    /// **Example:**
+    /// ### Example
     ///
     /// ```rust,ignore
     /// // Bad