From db3423f46a4e54f0f5aef16da2e263fee29770b5 Mon Sep 17 00:00:00 2001
From: Simon Farnsworth <simon@farnz.org.uk>
Date: Thu, 2 Apr 2020 10:03:15 +0100
Subject: [PATCH] Improve docs for option_option

Hint about using tri-state enums to replace legitimate uses of `Option<Option<_>>`
---
 clippy_lints/src/types.rs | 22 ++++++++++++++++++++--
 1 file changed, 20 insertions(+), 2 deletions(-)

diff --git a/clippy_lints/src/types.rs b/clippy_lints/src/types.rs
index b21c37392659..6b63f2b1f0a2 100644
--- a/clippy_lints/src/types.rs
+++ b/clippy_lints/src/types.rs
@@ -99,14 +99,32 @@ declare_clippy_lint! {
     /// 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**
-    /// ```rust
-    /// fn x() -> Option<Option<u32>> {
+    /// ```rust,ignore
+    /// fn get_node_data(n: Node) -> Option<Option<u32>> {
     ///     None
     /// }
     /// ```
+    ///
+    /// Better:
+    ///
+    /// ```rust,ignore
+    /// pub enum Contents {
+    ///     Data(Vec<u8>), // Was Some(Some(Vec<u8>))
+    ///     NotYetFetched, // Was Some(None)
+    ///     None,          // Was None
+    /// }
+    ///
+    /// fn get_node_data(n: Node) -> Contents {
+    ///     Contents::None
+    /// }
+    /// ```
+    ///
     pub OPTION_OPTION,
     pedantic,
     "usage of `Option<Option<T>>`"