linux-kernel - Re: [PATCH] checkpatch: warn on Rust comments with rustdoc links above items

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [day] [month] [year] [list]

Message-ID: <CANiq72me+h3kKzuUpvQCUqnJS7CHp+xbn2xdDaxaiyAS7qEe2Q@mail.gmail.com>
Date: Tue, 13 Jan 2026 23:38:23 +0100
From: Miguel Ojeda <miguel.ojeda.sandonis@...il.com>
To: Ryan Foster <foster.ryan.r@...il.com>
Cc: linux-kernel@...r.kernel.org, rust-for-linux@...r.kernel.org, 
	joe@...ches.com, ojeda@...nel.org
Subject: Re: [PATCH] checkpatch: warn on Rust comments with rustdoc links
 above items

On Tue, Jan 13, 2026 at 9:21 PM Ryan Foster <foster.ryan.r@...il.com> wrote:
>
> Add a check to emit a warning when a `//` comment containing rustdoc
> link patterns (like [`Foo`]) appears directly above a Rust item
> declaration. This likely indicates the comment should use `///`
> documentation syntax instead.
>
> The check uses heuristics to reduce false positives:
> - Only triggers on comments with rustdoc link syntax [`...`]
> - Excludes special comments (SAFETY:, TODO:, FIXME:, etc.)
> - Only warns when directly above a Rust item (fn, struct, enum, etc.)
>
> Examples that trigger the warning:
>     // Returns a reference to the underlying [`Table`].
>     fn table(&self) -> &Table { }
>
> Examples that do NOT trigger:
>     // SAFETY: The `ptr` is guaranteed by the C code to be valid.
>     unsafe fn foo() { }
>
>     // TODO: fix this later
>     fn bar() { }
>
>     // Regular comment without rustdoc links
>     fn baz() { }
>
> Link: https://github.com/Rust-for-Linux/linux/issues/1157
> Suggested-by: Miguel Ojeda <ojeda@...nel.org>

Yeah, the suggestion was mostly about detecting docs for private items
that used normal comments (`//`). For public items, the compiler
should already be warning on its own, but it doesn't hurt if
checkpatch does too, of course.

Did you get a lot of false positives without the logic to exclude "//
SAFETY: " etc.? I suggested that heuristics as a possible idea to
remove false positives if it was needed, but perhaps it was fine
without?

By the way, to clarify, for this example you give above:

    // SAFETY: The `ptr` is guaranteed by the C code to be valid.
    unsafe fn foo() { }

wouldn't hurt if it triggers either way, because it is actually wrong,
i.e. it should be a `# Safety` section (in this case I guess your lint
doesn't trigger because there is no intra-doc link anyway).

Thanks!

Cheers,
Miguel