unnecessary_safety_doc considered harmful

[asomers]

Summary

I disagree with the unnecessary_safety_doc warning. That's because a function's Safety section can document more than just the minimum requirements for calling the function safely. For example:

• It can document why a function is safe, even though the programmer expects that it wouldn't be:

/// # Safety
///
/// Safe because the pointer argument is validated through some mysterious back channel
pub fn foo(*const MyStruct) {...}

or this real-life example

/// # Safety
/// Safe because the pointer argument is unused
// But it's required to be present because the API is defined according to some external
// interface specification
#[no_mangle]
pub extern "C" fn foo(_td: *mut thread_data) -> libc::c_int {...}

or this real-life example: https://github.com/asomers/blosc-rs/blob/03c25105e4d1b78af8c1af2cba98f5c390dd7c9c/blosc/src/lib.rs#L363

• It can document how to use a function "safely", even though the compiler doesn't technically consider it unsafe.

/// # Safety
/// Though technically safe to use, this function is vulnerable to a race condition
/// and may return wrong results unless the caller does such and such.
pub fn foo() -> i64 {...}

or

/// # Safety
/// The returned pointer's lifetime will be such and such, and the caller is responsible
/// for freeing it with `Box::from_raw`.
pub fn foo() -> *const MyStruct {...}

Lint Name

unnecessary_safety_doc

Reproducer

I tried this code:

/// # Safety
///
/// Safe because the pointer argument is unused.
#[no_mangle]
pub extern "C" fn fio_bfffs_commit(_td: *mut thread_data) -> libc::c_int {
    unimplemented!()
}

I saw this happen:

warning: safe function's docs have unnecessary `# Safety` section

I expected to see this happen:
No warning

Version

rustc 1.67.0-nightly (2585bcea0 2022-11-28)
binary: rustc
commit-hash: 2585bcea0bc2a9c42a4be2c1eba5c61137f2b167
commit-date: 2022-11-28
host: x86_64-unknown-freebsd
release: 1.67.0-nightly
LLVM version: 15.0.4

Additional Labels

No response

[xFrednet]

I agree with this assessment. The lint should at least not be warn by default.

@rustbot claim