linux-kernel - Re: [PATCH v2 0/2] checkpatch.pl: Add warning for // 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: <CANiq72k4RJw3YENvQj5Q7LCG-v+nhZs=QhVa1AthUfZUoHmYdA@mail.gmail.com>
Date: Sun, 20 Apr 2025 21:48:33 +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 v2 0/2] checkpatch.pl: Add warning for // comments on
 private Rust items

On Sun, Apr 20, 2025 at 8:47 PM Arnaud Lecomte <contact@...aud-lcm.com> wrote:
>
> The Rust-for-Linux project currently lacks enforcement of documentation for private Rust items,
> as highlighted in https://github.com/Rust-for-Linux/linux/issues/1157.
> While rustc already lints missing documentation for public items, private items remain unchecked.
> This patch series aims to close that gap by ensuring proper documentation practices
> for private Rust items in the kernel.

To clarify, it is not that we want to enforce all private items to
have documentation, but rather to catch the odd `//` comment that was
supposed to be documentation. (The background here seems to imply the
former.)

> // Improper doc comment for a private function. - should trigger
> fn test() -> u32 {

Since this is just a `checkpatch.pl` warning, it may be fine to always
warn, i.e. the submitter can always decide if it is a false positive
or not -- I hope it does not become too annoying :)

(That is why the issue mentioned perhaps using some heuristics to decide).

> WARNING: Consider using `///` for private item documentation (line 33)

This text seems fine to me, although I wonder if newcomers to Rust may
just transform it into `///` when seeing this warning, i.e. the
opposite mistake. Perhaps we can make it more "conditional" (even if
the "Consider" is already there), e.g.

    Consider using `///` if this comment was intended as documentation

> To: Nathan Chancellor <nathan@...nel.org>
> To: Nick Desaulniers <nick.desaulniers+lkml@...il.com>
> To: Bill Wendling <morbo@...gle.com>
> To: Justin Stitt <justinstitt@...gle.com>
> Cc: llvm@...ts.linux.dev

Should the LLVM subsystem be Cc'd?

Thanks for the patches!

Cheers,
Miguel