linux-kernel - Re: [PATCH] rust: doc: Clean up formatting in io.rs

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: <CANiq72npoVzz01syorhUcED=tcs9FJf8bFHthFrUQ-bE-AXJ8Q@mail.gmail.com>
Date: Fri, 30 May 2025 21:39:30 +0200
From: Miguel Ojeda <miguel.ojeda.sandonis@...il.com>
To: Benno Lossin <lossin@...nel.org>
Cc: saivishnu725@...il.com, rust-for-linux@...r.kernel.org, 
	linux-kernel@...r.kernel.org, ojeda@...nel.org, alex.gaynor@...il.com, 
	boqun.feng@...il.com, gary@...yguo.net, bjorn3_gh@...tonmail.com, 
	a.hindborg@...nel.org, aliceryhl@...gle.com, tmgross@...ch.edu, 
	dakr@...nel.org, gregkh@...uxfoundation.org, daniel.almeida@...labora.com, 
	me@...enk.dev
Subject: Re: [PATCH] rust: doc: Clean up formatting in io.rs

On Fri, May 30, 2025 at 9:19 PM Benno Lossin <lossin@...nel.org> wrote:
>
> I would just remove the second part of the sentence. This is a struct
> and its only field is an `IoRaw`, which does have those two fields, but
> they are private, so nobody reading the docs will benefit from knowing
> this.

If we had something else talking about those things in the docs, it
could be useful to refer to them by an identifier, but I agree there
is nothing. Well, the invariants mention them, but those are a bit of
a special case.

An alternative to keep the sentence is to say "at a base ..." (i.e.
not "the") and "spanning a number of bytes" or similar.

We should also probably add "region" there, after "memory", or
similar, especially if we remove the second part.

Cheers,
Miguel