Auto merge of rust-lang#5403 - farnz:patch-1, r=flip1995

Improve docs for option_option

Hint about using tri-state enums to replace legitimate uses of `Option<Option<_>>`

changelog: The docs for `option_option` now suggest using a tri-state enum

clippy_lints/src/types.rs

@@ -99,14 +99,31 @@ 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>> {
+    /// fn get_data() -> Option<Option<u32>> {
     ///     None
     /// }
     /// ```
+    ///
+    /// Better:
+    ///
+    /// ```rust
+    /// pub enum Contents {
+    ///     Data(Vec<u8>), // Was Some(Some(Vec<u8>))
+    ///     NotYetFetched, // Was Some(None)
+    ///     None,          // Was None
+    /// }
+    ///
+    /// fn get_data() -> Contents {
+    ///     Contents::None
+    /// }
+    /// ```
     pub OPTION_OPTION,
     pedantic,
     "usage of `Option<Option<T>>`"