linux-kernel - Re: [PATCH V10 14/15] rust: opp: Extend OPP abstractions with cpufreq support

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] [thread-next>] [day] [month] [year] [list]

Message-ID: <CANiq72n_C7exSOMe5yf-7jKKnhSCv+a9QcD=OE2B_Q2UFBL3Xg@mail.gmail.com>
Date: Wed, 16 Apr 2025 12:47:29 +0200
From: Miguel Ojeda <miguel.ojeda.sandonis@...il.com>
To: Viresh Kumar <viresh.kumar@...aro.org>
Cc: Danilo Krummrich <dakr@...nel.org>, "Rafael J. Wysocki" <rafael@...nel.org>, 
	Danilo Krummrich <dakr@...hat.com>, Viresh Kumar <vireshk@...nel.org>, Nishanth Menon <nm@...com>, 
	Stephen Boyd <sboyd@...nel.org>, 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>, linux-pm@...r.kernel.org, 
	Vincent Guittot <vincent.guittot@...aro.org>, rust-for-linux@...r.kernel.org, 
	Manos Pitsidianakis <manos.pitsidianakis@...aro.org>, Alex Bennée <alex.bennee@...aro.org>, 
	Joakim Bech <joakim.bech@...aro.org>, Rob Herring <robh@...nel.org>, 
	Yury Norov <yury.norov@...il.com>, Burak Emir <bqe@...gle.com>, 
	Rasmus Villemoes <linux@...musvillemoes.dk>, Russell King <linux@...linux.org.uk>, 
	linux-clk@...r.kernel.org, Michael Turquette <mturquette@...libre.com>, 
	linux-kernel@...r.kernel.org
Subject: Re: [PATCH V10 14/15] rust: opp: Extend OPP abstractions with cpufreq support

On Wed, Apr 16, 2025 at 12:40 PM Viresh Kumar <viresh.kumar@...aro.org> wrote:
>
> Hmm, I did not use /// as the comments were added to private
> definitions.
>
> Sorry for the dumb question, but why should we use /// in such cases ?
> They will never show up in documentation anyway, right ?

It is not a dumb question at all!

The reason is that using `///` is not just for `rustdoc`, but intended
to convey it is documentation for the item, rather than a comment that
talks about implementation details or things like TODOs.

So you may have both `///` or `//` even for private items, and it is a
meaningful difference for the reader. Plus it makes it consistent with
the public ones.

Moreover, if we ever move to documenting private items, then we will
want these to be correct -- `rustdoc` supports generating docs with
private items (e.g. it puts a cute lock emoji on private items in the
lists etc.). I think some kernel developers would appreciate it -- we
could offer both versions in rust.docs.kernel.org with a toggle, for
instance.

Cheers,
Miguel