rust-lang / rust-lang/rust-clippy

proc_macros with safety docs trigger `unnecessary_safety_doc`

Open
#12,583 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

C-bug I-false-positive
Dominant language
Rust
Stars
13.5k
Forks
2.2k
Avg merge
2d 10h
Merged PRs (30d)
32

Description

Summary

Sometimes, proc_macros are written such that the code they generate requires that the macro be wrapped in an unsafe block. In order to inform users of the macros about the safety requirements of the macro, a safety doc is added to the proc macro. This triggers clippy's unnecessary_safety_doc lint, even though the code the proc-macro generates does actually require unsafe.

My guess here is that since the doc must be attached to the #[proc_macro] fn and that fn is not unsafe, it triggers this lint. I think proc_macro fns should automatically be opted out of unnecessary_safety_doc.

Lint Name

unnecessary_safety_doc

Reproducer

I tried this code:

#![forbid(clippy::unnecessary_safety_doc)]

use proc_macro::TokenStream;
use quote::quote;

/// An unsafe proc_macro
///
/// # Safety
/// This macro is only safe to call when XYZ
#[proc_macro]
pub fn unsafe_macro(_: TokenStream) -> TokenStream {
    quote! {
        unsafe fn unsafe_fn() {

        }

        unsafe_fn()
    }.into()
}

I saw this happen:

cargo +nightly clippy
   Compiling proc-macro2 v1.0.79
    Checking unicode-ident v1.0.12
    Checking quote v1.0.35
    Checking proc-macro-unnecessary_safety_doc v0.1.0 (D:\git-repos\proc-macro-unnecessary_safety_doc)
error[E0453]: allow(clippy::unnecessary_safety_doc) incompatible with previous forbid
  --> src\lib.rs:10:9
   |
1  | #![forbid(clippy::unnecessary_safety_doc)]
   |           ------------------------------ `forbid` level set here
...
10 | #[allow(clippy::unnecessary_safety_doc)]
   |         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ overruled by previous forbid

For more information about this error, try `rustc --explain E0453`.
error: could not compile `proc-macro-unnecessary_safety_doc` (lib) due to 1 previous error

I expected to see this happen:
No lint thrown.

Version
cargo +nightly rustc -- --version -v
   Compiling proc-macro-unnecessary_safety_doc v0.1.0 (D:\git-repos\proc-macro-unnecessary_safety_doc)
rustc 1.79.0-nightly (5f2c7d2bf 2024-03-25)
binary: rustc
commit-hash: 5f2c7d2bfd46cad00352ab7cd66242077e2e518c
commit-date: 2024-03-25
host: x86_64-pc-windows-msvc
release: 1.79.0-nightly
LLVM version: 18.1.2
    Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.14s
Additional Labels

No response

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Reproduce the report with the supplied proc-macro example and the unnecessary_safety_doc lint enabled. Then trace the lint's implementation and existing tests to determine how proc_macro functions are handled; done means the safety documentation no longer triggers this lint for proc-macro functions while other cases retain their checks.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
tooling
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.