linux-kernel - Re: [PATCH v3 1/2] checkpatch.pl: warn about // comments on private Rust 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: <CANiq72=UOOyf-esnRUCR0_gxFptdpNOymCz02vgesdNL7zTvHg@mail.gmail.com>
Date: Tue, 22 Apr 2025 17:32:36 +0200
From: Miguel Ojeda <miguel.ojeda.sandonis@...il.com>
To: Arnaud Lecomte <contact@...aud-lcm.com>
Cc: Andy Whitcroft <apw@...onical.com>, Joe Perches <joe@...ches.com>, 
	Dwaipayan Ray <dwaipayanray1@...il.com>, Lukas Bulwahn <lukas.bulwahn@...il.com>, 
	Miguel Ojeda <ojeda@...nel.org>, Alex Gaynor <alex.gaynor@...il.com>, 
	Boqun Feng <boqun.feng@...il.com>, Gary Guo <gary@...yguo.net>, 
	Björn Roy Baron <bjorn3_gh@...tonmail.com>, 
	Benno Lossin <benno.lossin@...ton.me>, Andreas Hindborg <a.hindborg@...nel.org>, 
	Alice Ryhl <aliceryhl@...gle.com>, Trevor Gross <tmgross@...ch.edu>, 
	Danilo Krummrich <dakr@...nel.org>, Nathan Chancellor <nathan@...nel.org>, 
	Nick Desaulniers <nick.desaulniers+lkml@...il.com>, Bill Wendling <morbo@...gle.com>, 
	Justin Stitt <justinstitt@...gle.com>, linux-kernel@...r.kernel.org, 
	rust-for-linux@...r.kernel.org, llvm@...ts.linux.dev, 
	skhan@...uxfoundation.org
Subject: Re: [PATCH v3 1/2] checkpatch.pl: warn about // comments on private
 Rust items

On Tue, Apr 22, 2025 at 4:37 PM Arnaud Lecomte <contact@...aud-lcm.com> wrote:
>
> As mentioned earlier, we can reduce the score of any heuristic which
> could lead to any important false positive.
> In my opinion, as long as the heuristic is relevant, we always have the
> possibility to diminish the score associated with the heuristic, hence
> preventing unnecessary false positives.

Definitely (my comment above for this one was just a note, i.e. there
may be nothing to change -- I just thought the commit message referred
to just checking "Return" and not "Returns", since it said
"imperative").

> I think that you are definitely more experienced with what's done
> commonly in rust code. Let's maybe change this heuristic definition with
> @ related to types or some other annotation. Do you have some example I
> could have a look to come in the next version with a relevant list of @
> we can encounter.

What does "references" mean in that heuristic? If you mean external
links to some URL, then we typically use Markdown for those. The
inline ones like `<https://...>`happen in both comments and docs. The
`[...]: https://...` ones are way less common in comments I think (I
can't find one).

As for `@`, if you mean the actual character, I grepped for it in Rust
files with the /.*@ regex and found just ~13 matches, and all were the
emails and disambiguators I mentioned. So I don't think we really use
it for "references" (assuming I understand what that means).

I guess you already looked in some `rust/kernel/` files -- some of
those are really the best examples of how docs and comments should
generally be written.

Thanks!

Cheers,
Miguel