linux-kernel - Re: [PATCH v3 1/3] rust: Add soc

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 for Android: free password hash cracker in your pocket

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

Message-ID: <CANiq72mNuWE_K128Ona03PATjFkSX3y7R-yjw3G0iOBQ+p+WRw@mail.gmail.com>
Date: Sun, 28 Dec 2025 12:21:28 +0100
From: Miguel Ojeda <miguel.ojeda.sandonis@...il.com>
To: Matthew Maurer <mmaurer@...gle.com>
Cc: Alexandre Courbot <acourbot@...dia.com>, Miguel Ojeda <ojeda@...nel.org>, 
	Boqun Feng <boqun.feng@...il.com>, Gary Guo <gary@...yguo.net>, 
	Björn Roy Baron <bjorn3_gh@...tonmail.com>, 
	Benno Lossin <lossin@...nel.org>, Andreas Hindborg <a.hindborg@...nel.org>, 
	Alice Ryhl <aliceryhl@...gle.com>, Trevor Gross <tmgross@...ch.edu>, 
	Danilo Krummrich <dakr@...nel.org>, Greg Kroah-Hartman <gregkh@...uxfoundation.org>, 
	"Rafael J. Wysocki" <rafael@...nel.org>, linux-kernel@...r.kernel.org, 
	rust-for-linux@...r.kernel.org
Subject: Re: [PATCH v3 1/3] rust: Add soc_device support

On Fri, Dec 26, 2025 at 8:38 PM Matthew Maurer <mmaurer@...gle.com> wrote:
>
> I don't think I should do this unless there's some kernel-specific
> style guidance I'm unaware of (I checked and couldn't find anything,
> but maybe I missed something):

So we don't require private docs, but developers are always welcome to
add them. It really depends on a case-by-case basis: sometimes docs
are really needed, even if private, and other times not so much. Thus,
so far, I considered it was best to leave it to the developer and see
how code evolves.

In the future, the value/benefit of private docs may increase: I would
like to have a runtime toggle for the user that shows/hides private
and/or hidden items in the rendered docs, thus treating them as
first-class docs (including e.g. checking their intra-doc links work).
Upstream `rustdoc` seems to like the idea and even they even
implemented a draft of it (see
https://github.com/Rust-for-Linux/linux/issues/350 -> "private/hidden
items").

Comments vs. docs is an orthogonal part of this, and indeed, we use
comments for implementation-oriented things, and docs for the users
(and mixing them in the same place is also OK -- there is an example
of that in our guidelines that I wrote for clarity). There are some
exceptions and cases where it is reasonable to have either position
but, generally, we should avoid aim to avoid details that are clearly
implementation details in code documentation and vice versa.

As a rule of thumb: if a Rust item would have needed good docs to be
understandable if it were public (or became public later on), then it
should also have those docs even if it is private.

Cheers,
Miguel