Auto merge of #5087 - Areredify:issue-4905, r=phansch

improve `empty_enum` documentation

closes #4905
changelog: improve `empty_enum` help message and documentation.

2 files changed, 19 insertions, 5 deletions

diff --git a/clippy_lints/src/empty_enum.rs b/clippy_lints/src/empty_enum.rs
index 0a8d9977845..c43db68d20f 100644
--- a/clippy_lints/src/empty_enum.rs
+++ b/clippy_lints/src/empty_enum.rs
@@ -8,16 +8,29 @@ use rustc_session::{declare_lint_pass, declare_tool_lint};
 declare_clippy_lint! {
     /// **What it does:** Checks for `enum`s with no variants.
     ///
-    /// **Why is this bad?** Enum's with no variants should be replaced with `!`,
-    /// the uninhabited type,
-    /// or a wrapper around it.
+    /// **Why is this bad?** If you want to introduce a type which
+    /// can't be instantiated, you should use `!` (the never type),
+    /// or a wrapper around it, because `!` has more extensive
+    /// compiler support (type inference, etc...) and wrappers
+    /// around it are the conventional way to define an uninhabited type.
+    /// For further information visit [never type documentation](https://doc.rust-lang.org/std/primitive.never.html)
+    ///
     ///
     /// **Known problems:** None.
     ///
     /// **Example:**
+    ///
+    /// Bad:
     /// ```rust
     /// enum Test {}
     /// ```
+    ///
+    /// Good:
+    /// ```rust
+    /// #![feature(never_type)]
+    ///
+    /// struct Test(!);
+    /// ```
     pub EMPTY_ENUM,
     pedantic,
     "enum with no variants"
@@ -35,7 +48,8 @@ impl<'a, 'tcx> LateLintPass<'a, 'tcx> for EmptyEnum {
                 span_lint_and_then(cx, EMPTY_ENUM, item.span, "enum with no variants", |db| {
                     db.span_help(
                         item.span,
-                        "consider using the uninhabited type `!` or a wrapper around it",
+                        "consider using the uninhabited type `!` (never type) or a wrapper \
+                         around it to introduce a type which can't be instantiated",
                     );
                 });
             }
diff --git a/tests/ui/empty_enum.stderr b/tests/ui/empty_enum.stderr
index 223a14ed877..b1e4eb27755 100644
--- a/tests/ui/empty_enum.stderr
+++ b/tests/ui/empty_enum.stderr
@@ -5,7 +5,7 @@ LL | enum Empty {}
    | ^^^^^^^^^^^^^
    |
    = note: `-D clippy::empty-enum` implied by `-D warnings`
-help: consider using the uninhabited type `!` or a wrapper around it
+help: consider using the uninhabited type `!` (never type) or a wrapper around it to introduce a type which can't be instantiated
   --> $DIR/empty_enum.rs:4:1
    |
 LL | enum Empty {}