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

[Miguel Ojeda]

On Tue, Jan 13, 2026 at 9:21 PM Ryan Foster <foster.ryan.r@xxxxxxxxx> 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@xxxxxxxxxx>

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