unnecessary_safety_doc considered harmful · Issue #9986 · rust-lang/rust-clippy (original) (raw)

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