Auto merge of #8954 - Serial-ATA:doc-comment-issues, r=xFrednet

Improve lint doc consistency

changelog: none

This is a continuation of #8908.

Notable changes:
- Removed empty `Known Problems` sections
- Removed "Good"/"Bad" language (replaced with "Use instead")
- Removed (and added some 😄) duplication
- Ignored the [`create_dir`] example so it doesn't create `clippy_lints/foo` 😄

clippy_lints/src/lib.rs

@@ -88,10 +88,11 @@ use rustc_session::Session;
 ///     ///
 ///     /// ### Example
 ///     /// ```rust
-///     /// // Bad
 ///     /// Insert a short example of code that triggers the lint
+///     /// ```
 ///     ///
-///     /// // Good
+///     /// Use instead:
+///     /// ```rust
 ///     /// Insert a short example of improved code that doesn't trigger the lint
 ///     /// ```
 ///     pub LINT_NAME,