rust: doc: Clean up formatting in io.rs
Subsystems (2)
PATCH 1/1 rust: doc: Clean up formatting in io.rs
From: Sai Vishnu M <[email protected]>
Replace @ with backticks in a comment of io.rs to follow Rust doc convention
--- rust/kernel/io.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
rust/kernel/io.rs +1 -1
@@ -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.
Signature · 1 line
2.49.0
Benno Lossin
reviewerQuoted 17 lines · On Fri May 30, 2025 at 2:31 PM CEST, saivishnu725 wrote:
From: Sai Vishnu M <[email protected]>
Replace
@with backticks in a comment ofio.rsto follow Rust doc conventionReported-by Miguel Ojeda <[email protected]>Signed-off-by Sai Vishnu M <[email protected]>--- rust/kernel/io.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)rust/kernel/io.rs +0
-0
rust/kernel/io.rs pub fn maxsize(&self) -> usize { · line 46
Quoted 5 lines
rust/kernel/io.rs +1
-1@@ -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
Quoted 3 lines
rust/kernel/io.rs +0
-0/// /// The creator (usually a subsystem / bus such as PCI) is responsible for creating the /// mapping, performing an additional region request etc.
Quoted 5 lines · Benno Lossin
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
Quoted 3 lines · Miguel Ojeda
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!
Benno Lossin
reviewerQuoted 6 lines · Sai Vishnu
Quoted 3 lines · Miguel Ojeda
We should also probably add "region" there, after "memory", or similar, especially if we remove the second part.
Quoted 6 lines
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