From 58fe45102de21fb0806f7f58e85ce1f4ec7e490e Mon Sep 17 00:00:00 2001
From: Wilfred Hughes <wilfred@meta.com>
Date: Fri, 27 Oct 2023 10:22:41 -0700
Subject: [PATCH] Expand docs on clippy::todo

https://doc.rust-lang.org/nightly/core/macro.todo.html
describes that `todo!()` is intended for explicitly unfinished
code. Explain this, and mention `unimplemented!()` as an alternative.

Whilst we're here, improve the punctuation on the other lints.
---
 clippy_lints/src/panic_unimplemented.rs | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)

diff --git a/clippy_lints/src/panic_unimplemented.rs b/clippy_lints/src/panic_unimplemented.rs
index a72aefe91c12..f4f1f6ddb3f2 100644
--- a/clippy_lints/src/panic_unimplemented.rs
+++ b/clippy_lints/src/panic_unimplemented.rs
@@ -9,7 +9,7 @@ declare_clippy_lint! {
     /// Checks for usage of `panic!`.
     ///
     /// ### Why is this bad?
-    /// `panic!` will stop the execution of the executable
+    /// `panic!` will stop the execution of the executable.
     ///
     /// ### Example
     /// ```no_run
@@ -26,7 +26,7 @@ declare_clippy_lint! {
     /// Checks for usage of `unimplemented!`.
     ///
     /// ### Why is this bad?
-    /// This macro should not be present in production code
+    /// This macro should not be present in production code.
     ///
     /// ### Example
     /// ```no_run
@@ -43,12 +43,17 @@ declare_clippy_lint! {
     /// Checks for usage of `todo!`.
     ///
     /// ### Why is this bad?
-    /// This macro should not be present in production code
+    /// The `todo!` macro is often used for unfinished code, and it causes
+    /// code to panic. It should not be present in production code.
     ///
     /// ### Example
     /// ```no_run
     /// todo!();
     /// ```
+    /// Finish the implementation, or consider marking it as explicitly unimplemented.
+    /// ```no_run
+    /// unimplemented!();
+    /// ```
     #[clippy::version = "1.40.0"]
     pub TODO,
     restriction,
@@ -60,7 +65,7 @@ declare_clippy_lint! {
     /// Checks for usage of `unreachable!`.
     ///
     /// ### Why is this bad?
-    /// This macro can cause code to panic
+    /// This macro can cause code to panic.
     ///
     /// ### Example
     /// ```no_run