New Lint: Unsafe block in safe functions without SAFETY comment

[fee1-dead]

What it does

Detects unsafe blocks used in safe functions missing a comment explaining/justifying the use of unsafe.

Categories (optional)

• Kind: clippy::pedantic

What is the advantage of the recommended code over the original code

• Explains why the use of unsafe in the function is okay
• Makes it easier to maintain

Drawbacks

None.

Example

fn get(self, slice: &[T]) -> Option<T> {
  if self < slice.len() { unsafe { Some(&*self.get_unchecked(slice)) } } else { None }
}

Could be written as:

fn get(self, slice: &[T]) -> Option<T> {
  // SAFETY: `self` is checked to be in bounds.
  if self < slice.len() { unsafe { Some(&*self.get_unchecked(slice)) } } else { None }
}

[giraffate]

From API guidelines, unsafe functions should be documented with a "Safety" section, so why do you want it with unsafe blocks?

FYI

• Clippy has the missing_safety_doc lint.
• Clippy can't find just comment. Doc comments is ok.

[fee1-dead]

There are some requirements for a call to an unsafe function to be safe. A comment with unsafe blocks can explain how the safety contract is respected. As shown in the example, it could be easier to maintain if the developer knows that unsafe block has been checked. This new lint can help developers to make sure that all usage of unsafe is documented.

For checking comments, I don't know if there is a solution. The Rust repository does document their usage of unsafe so I thought "why not a lint?"

[PatchMixolydic]

An implementation for this seems to be in the works: #7557

[fee1-dead]

Since #7748 was merged, I am closing this.