1 files changed, 43 insertions, 0 deletions
diff --git a/src/tools/clippy/src/docs/undocumented_unsafe_blocks.txt b/src/tools/clippy/src/docs/undocumented_unsafe_blocks.txt
new file mode 100644
index 000000000..f3af4753c
--- /dev/null
+++ b/src/tools/clippy/src/docs/undocumented_unsafe_blocks.txt
@@ -0,0 +1,43 @@
+### What it does
+Checks for `unsafe` blocks and impls without a `// SAFETY: ` comment
+explaining why the unsafe operations performed inside
+the block are safe.
+
+Note the comment must appear on the line(s) preceding the unsafe block
+with nothing appearing in between. The following is ok:
+```
+foo(
+    // SAFETY:
+    // This is a valid safety comment
+    unsafe { *x }
+)
+```
+But neither of these are:
+```
+// SAFETY:
+// This is not a valid safety comment
+foo(
+    /* SAFETY: Neither is this */ unsafe { *x },
+);
+```
+
+### Why is this bad?
+Undocumented unsafe blocks and impls can make it difficult to
+read and maintain code, as well as uncover unsoundness
+and bugs.
+
+### Example
+```
+use std::ptr::NonNull;
+let a = &mut 42;
+
+let ptr = unsafe { NonNull::new_unchecked(a) };
+```
+Use instead:
+```
+use std::ptr::NonNull;
+let a = &mut 42;
+
+// SAFETY: references are guaranteed to be non-null.
+let ptr = unsafe { NonNull::new_unchecked(a) };
+```
+\ No newline at end of file