Skip to contentSkip to conversation

rust: doc: Clean up formatting in io.rs

PATCH Superseded [email protected] 3 participants 5 messages May 30, 2025 – May 31, 2025

Subsystems (2)

v1 of 4 Superseded Latest is v4 →

lore
Share & tools
lore
#0 lore raw

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
index 72d80a6f131e..92bc4e3cd8ec 100644
@@ -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
reviewer
#1 lore raw
Quoted 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 of io.rs to follow Rust doc convention

---
 rust/kernel/io.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
rust/kernel/io.rs +0 -0
index 72d80a6f131e..92bc4e3cd8ec 100644

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.
#2 lore raw
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

author
#3 lore raw
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!

reviewer
#4 lore raw
Quoted 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