[v1] rust: doc: Clean up formatting in io.rs

[PATCH] rust: doc: Clean up formatting in io.rs

Posted by saivishnu725@gmail.com 6 months, 2 weeks ago

From: Sai Vishnu M <saivishnu725@gmail.com>

Replace `@` with backticks in a comment of `io.rs` to follow Rust doc
convention

Reported-by: Miguel Ojeda <ojeda@kernel.org>
Closes: https://github.com/Rust-for-Linux/linux/issues/1167
Signed-off-by: Sai Vishnu M <saivishnu725@gmail.com>
---
 rust/kernel/io.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/rust/kernel/io.rs b/rust/kernel/io.rs
index 72d80a6f131e..92bc4e3cd8ec 100644
--- a/rust/kernel/io.rs
+++ b/rust/kernel/io.rs
@@ -43,7 +43,7 @@ pub fn maxsize(&self) -> usize {
     }
 }
 
-/// IO-mapped memory, starting at the base address @addr and spanning @maxlen bytes.
+/// IO-mapped memory, starting at the base address `addr` and spanning `maxlen` bytes.
 ///
 /// The creator (usually a subsystem / bus such as PCI) is responsible for creating the
 /// mapping, performing an additional region request etc.
-- 
2.49.0

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

Posted by Benno Lossin 6 months, 2 weeks ago

On Fri May 30, 2025 at 2:31 PM CEST, saivishnu725 wrote:
> From: Sai Vishnu M <saivishnu725@gmail.com>
>
> Replace `@` with backticks in a comment of `io.rs` to follow Rust doc
> convention
>
> Reported-by: Miguel Ojeda <ojeda@kernel.org>
> Closes: https://github.com/Rust-for-Linux/linux/issues/1167
> Signed-off-by: Sai Vishnu M <saivishnu725@gmail.com>
> ---
>  rust/kernel/io.rs | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/rust/kernel/io.rs b/rust/kernel/io.rs
> index 72d80a6f131e..92bc4e3cd8ec 100644
> --- a/rust/kernel/io.rs
> +++ b/rust/kernel/io.rs
> @@ -43,7 +43,7 @@ pub fn maxsize(&self) -> usize {
>      }
>  }
>  
> -/// IO-mapped memory, starting at the base address @addr and spanning @maxlen bytes.
> +/// IO-mapped memory, starting at the base address `addr` and spanning `maxlen` bytes.

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.

---
Cheers,
Benno

>  ///
>  /// The creator (usually a subsystem / bus such as PCI) is responsible for creating the
>  /// mapping, performing an additional region request etc.

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

Posted by Miguel Ojeda 6 months, 2 weeks ago

On Fri, May 30, 2025 at 9:19 PM Benno Lossin <lossin@kernel.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

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

Posted by Sai Vishnu 6 months, 2 weeks ago

On Sat, May 31, 2025 at 1:09 AM Miguel Ojeda
<miguel.ojeda.sandonis@gmail.com> wrote:
>
> We should also probably add "region" there, after "memory", or
> similar, especially if we remove the second part.

Thanks for the feedback! I’ve decided to update the comment to just:

/// IO-mapped memory

I’m new to kernel development. Should I just share the updated patch
here or send a v2 that refers to this one? Thanks!

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

Posted by Benno Lossin 6 months, 2 weeks ago

On Sat May 31, 2025 at 4:57 AM CEST, Sai Vishnu wrote:
> On Sat, May 31, 2025 at 1:09 AM Miguel Ojeda
> <miguel.ojeda.sandonis@gmail.com> wrote:
>>
>> We should also probably add "region" there, after "memory", or
>> similar, especially if we remove the second part.
>
> Thanks for the feedback! I’ve decided to update the comment to just:
>
> /// IO-mapped memory
>
> I’m new to kernel development. Should I just share the updated patch
> here or send a v2 that refers to this one? Thanks!

Normally, you send a v2 with a changelog and a link to each previous
version. For patch series with a cover letter it is often placed there.
Since you don't need one, you should put the changelog after the `---`
(anything that isn't a diff there will be ignored by git when applying).

I'd give others a few more days to review. (this patch there most likely
won't be any additional comments, but it also doesn't hurt)

---
Cheers,
Benno