src/docs/undocumented_unsafe_blocks.txt

   1 ### What it does
   2 Checks for `unsafe` blocks and impls without a `// SAFETY: ` comment
   3 explaining why the unsafe operations performed inside
   4 the block are safe.
   5
   6 Note the comment must appear on the line(s) preceding the unsafe block
   7 with nothing appearing in between. The following is ok:
   8 ```
   9 foo(
  10     // SAFETY:
  11     // This is a valid safety comment
  12     unsafe { *x }
  13 )
  14 ```
  15 But neither of these are:
  16 ```
  17 // SAFETY:
  18 // This is not a valid safety comment
  19 foo(
  20     /* SAFETY: Neither is this */ unsafe { *x },
  21 );
  22 ```
  23
  24 ### Why is this bad?
  25 Undocumented unsafe blocks and impls can make it difficult to
  26 read and maintain code, as well as uncover unsoundness
  27 and bugs.
  28
  29 ### Example
  30 ```
  31 use std::ptr::NonNull;
  32 let a = &mut 42;
  33
  34 let ptr = unsafe { NonNull::new_unchecked(a) };
  35 ```
  36 Use instead:
  37 ```
  38 use std::ptr::NonNull;
  39 let a = &mut 42;
  40
  41 // SAFETY: references are guaranteed to be non-null.
  42 let ptr = unsafe { NonNull::new_unchecked(a) };
  43 ```