Update lint description and add help section

Co-authored-by: Weihang Lo <me@weihanglo.tw>

2 files changed, 46 insertions, 9 deletions

diff --git a/clippy_lints/src/missing_assert_message.rs b/clippy_lints/src/missing_assert_message.rs
index 07424eb46a4..3b73332215e 100644
--- a/clippy_lints/src/missing_assert_message.rs
+++ b/clippy_lints/src/missing_assert_message.rs
@@ -1,4 +1,4 @@
-use clippy_utils::diagnostics::span_lint;
+use clippy_utils::diagnostics::span_lint_and_help;
 use rustc_ast::ast;
 use rustc_ast::{
     token::{Token, TokenKind},
@@ -13,19 +13,23 @@ declare_clippy_lint! {
     /// Checks assertions without a custom panic message.
     ///
     /// ### Why is this bad?
-    /// If the assertion fails, the custom message may make it easier to understand what went wrong.
+    /// Without a good custom message, it'd be hard to understand what went wrong when the assertion fails.
+    /// A good custom message should be more about why the failure of the assertion is problematic
+    /// and not what is failed because the assertion already conveys that.
     ///
     /// ### Example
     /// ```rust
-    /// let threshold = 50;
-    /// let num = 42;
-    /// assert!(num < threshold);
+    /// # struct Service { ready: bool }
+    /// fn call(service: Service) {
+    ///     assert!(service.ready);
+    /// }
     /// ```
     /// Use instead:
     /// ```rust
-    /// let threshold = 50;
-    /// let num = 42;
-    /// assert!(num < threshold, "{num} is lower than threshold ({threshold})");
+    /// # struct Service { ready: bool }
+    /// fn call(service: Service) {
+    ///     assert!(service.ready, "`service.poll_ready()` must be called first to ensure that service is ready to receive requests");
+    /// }
     /// ```
     #[clippy::version = "1.69.0"]
     pub MISSING_ASSERT_MESSAGE,
@@ -56,11 +60,13 @@ impl EarlyLintPass for MissingAssertMessage {
         let num_separators = num_commas_on_arguments(mac_call);
 
         if num_separators < num_separators_needed {
-            span_lint(
+            span_lint_and_help(
                 cx,
                 MISSING_ASSERT_MESSAGE,
                 mac_call.span(),
                 "assert without any message",
+                None,
+                "consider describing why the failing assert is problematic",
             );
         }
     }
diff --git a/tests/ui/missing_assert_message.stderr b/tests/ui/missing_assert_message.stderr
index 900966500c8..ecd03801277 100644
--- a/tests/ui/missing_assert_message.stderr
+++ b/tests/ui/missing_assert_message.stderr
@@ -4,6 +4,7 @@ error: assert without any message
 LL |     assert!(foo());
    |     ^^^^^^^^^^^^^^
    |
+   = help: consider describing why the failing assert is problematic
    = note: `-D clippy::missing-assert-message` implied by `-D warnings`
 
 error: assert without any message
@@ -11,90 +12,120 @@ error: assert without any message
    |
 LL |     assert_eq!(foo(), foo());
    |     ^^^^^^^^^^^^^^^^^^^^^^^^
+   |
+   = help: consider describing why the failing assert is problematic
 
 error: assert without any message
   --> $DIR/missing_assert_message.rs:16:5
    |
 LL |     assert_ne!(foo(), foo());
    |     ^^^^^^^^^^^^^^^^^^^^^^^^
+   |
+   = help: consider describing why the failing assert is problematic
 
 error: assert without any message
   --> $DIR/missing_assert_message.rs:17:5
    |
 LL |     debug_assert!(foo());
    |     ^^^^^^^^^^^^^^^^^^^^
+   |
+   = help: consider describing why the failing assert is problematic
 
 error: assert without any message
   --> $DIR/missing_assert_message.rs:18:5
    |
 LL |     debug_assert_eq!(foo(), foo());
    |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+   |
+   = help: consider describing why the failing assert is problematic
 
 error: assert without any message
   --> $DIR/missing_assert_message.rs:19:5
    |
 LL |     debug_assert_ne!(foo(), foo());
    |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+   |
+   = help: consider describing why the failing assert is problematic
 
 error: assert without any message
   --> $DIR/missing_assert_message.rs:24:5
    |
 LL |     assert!(bar!(true));
    |     ^^^^^^^^^^^^^^^^^^^
+   |
+   = help: consider describing why the failing assert is problematic
 
 error: assert without any message
   --> $DIR/missing_assert_message.rs:25:5
    |
 LL |     assert!(bar!(true, false));
    |     ^^^^^^^^^^^^^^^^^^^^^^^^^^
+   |
+   = help: consider describing why the failing assert is problematic
 
 error: assert without any message
   --> $DIR/missing_assert_message.rs:26:5
    |
 LL |     assert_eq!(bar!(true), foo());
    |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+   |
+   = help: consider describing why the failing assert is problematic
 
 error: assert without any message
   --> $DIR/missing_assert_message.rs:27:5
    |
 LL |     assert_ne!(bar!(true, true), bar!(true));
    |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+   |
+   = help: consider describing why the failing assert is problematic
 
 error: assert without any message
   --> $DIR/missing_assert_message.rs:32:5
    |
 LL |     assert!(foo(),);
    |     ^^^^^^^^^^^^^^^
+   |
+   = help: consider describing why the failing assert is problematic
 
 error: assert without any message
   --> $DIR/missing_assert_message.rs:33:5
    |
 LL |     assert_eq!(foo(), foo(),);
    |     ^^^^^^^^^^^^^^^^^^^^^^^^^
+   |
+   = help: consider describing why the failing assert is problematic
 
 error: assert without any message
   --> $DIR/missing_assert_message.rs:34:5
    |
 LL |     assert_ne!(foo(), foo(),);
    |     ^^^^^^^^^^^^^^^^^^^^^^^^^
+   |
+   = help: consider describing why the failing assert is problematic
 
 error: assert without any message
   --> $DIR/missing_assert_message.rs:35:5
    |
 LL |     debug_assert!(foo(),);
    |     ^^^^^^^^^^^^^^^^^^^^^
+   |
+   = help: consider describing why the failing assert is problematic
 
 error: assert without any message
   --> $DIR/missing_assert_message.rs:36:5
    |
 LL |     debug_assert_eq!(foo(), foo(),);
    |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+   |
+   = help: consider describing why the failing assert is problematic
 
 error: assert without any message
   --> $DIR/missing_assert_message.rs:37:5
    |
 LL |     debug_assert_ne!(foo(), foo(),);
    |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+   |
+   = help: consider describing why the failing assert is problematic
 
 error: aborting due to 16 previous errors