1 files changed, 32 insertions, 0 deletions
diff --git a/src/tools/clippy/src/docs/option_option.txt b/src/tools/clippy/src/docs/option_option.txt
new file mode 100644
index 000000000..b4324bd83
--- /dev/null
+++ b/src/tools/clippy/src/docs/option_option.txt
@@ -0,0 +1,32 @@
+### What it does
+Checks for use of `Option<Option<_>>` in function signatures and type
+definitions
+
+### Why is this bad?
+`Option<_>` represents an optional value. `Option<Option<_>>`
+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.
+
+### Example
+```
+fn get_data() -> Option<Option<u32>> {
+    None
+}
+```
+
+Better:
+
+```
+pub enum Contents {
+    Data(Vec<u8>), // Was Some(Some(Vec<u8>))
+    NotYetFetched, // Was Some(None)
+    None,          // Was None
+}
+
+fn get_data() -> Contents {
+    Contents::None
+}
+```
+\ No newline at end of file