Skip to contentSkip to conversation

rust: doc: Clean up formatting in io.rs

PATCH Superseded Sai Vishnu M 3 participants 5 messages Jun 2, 2025

Subsystems (2)

v3 of 4 Superseded Latest is v4 →

lore
Share & tools
lore
#0 lore raw

PATCH v3 1/1 rust: doc: Clean up formatting in io.rs

From: Sai Vishnu M <[email protected]>

Removed reference to internal variables in the comment of IoMem This avoids using private variable names in public documentation.

---
 rust/kernel/io.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
rust/kernel/io.rs +1 -1
index 72d80a6f131e..41404c1e17b3 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 region.
 ///
 /// The creator (usually a subsystem / bus such as PCI) is responsible for creating the
 /// mapping, performing an additional region request etc.

v1: Used backticks instead of @ for parameters

v2: removed reference to the variable entirely.

v3: Moved changelog to commit message. Used the proper parent commit.

base-commit: 7a17bbc1d952057898cb0739e60665908fbb8c72

Signature · 1 line
2.49.0
#1 lore raw
Quoted 27 lines · Sai Vishnu M

From: Sai Vishnu M <[email protected]>

Removed reference to internal variables in the comment of IoMem This avoids using private variable names in public documentation.

---
 rust/kernel/io.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
rust/kernel/io.rs +1 -1
index 72d80a6f131e..41404c1e17b3 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 region.
 ///
 /// The creator (usually a subsystem / bus such as PCI) is responsible for creating the
 /// mapping, performing an additional region request etc.
Quoted 7 lines

v1: Used backticks instead of @ for parameters

v2: removed reference to the variable entirely.

v3: Moved changelog to commit message. Used the proper parent commit.

All of this "version" text needs to below the first --- line, as the kernel documentation describes. Putting it down here makes it so the patch will not apply at all :(

thanks,

greg k-h

author
#2 lore raw
Quoted 1 line

below the first --- line

Is it the one below the Signed off by line? To get the complete picture:
1. commit title
2. commit message
3. signed off and other tags
---
4. The version log or any other necessary comments
5. actual diff
---

Additionally, I suppose the base-commit tag should also be placed in 3 (above/below Signed-off-by), as it was added to the very end by git when generating the patch.
I am sincerely apologizing for taking at least 4 versions for a simple fix, but I am trying to figure out how to properly create and send patches.
This clearly explains what you meant:
https://www.kernel.org/doc/html/latest/process/submitting-patches.html#commentary
.
I will send v4 after thoroughly reading it multiple times.

Thanks for all the time and patience!

#3 lore raw
Quoted 11 lines · Sai Vishnu
Quoted 1 line

below the first --- line

Is it the one below the Signed off by line? To get the complete picture:
1. commit title
2. commit message
3. signed off and other tags
---
4. The version log or any other necessary comments
5. actual diff
---

Quoted 3 lines

Additionally, I suppose the base-commit tag should also be placed in 3 (above/below Signed-off-by), as it was added to the very end by git when generating the patch.

No, that is fine.

Quoted 5 lines

I am sincerely apologizing for taking at least 4 versions for a simple fix, but I am trying to figure out how to properly create and send patches.
This clearly explains what you meant:
https://www.kernel.org/doc/html/latest/process/submitting-patches.html#commentary

Yes, that is what you should be reading.

Also see the thousands of examples of good patches on the mailing lists for real-world examples.

thanks,

greg k-h

#4 lore raw
In reply to Sai Vishnu
Quoted 2 lines · Sai Vishnu

Is it the one below the Signed off by line? To get the complete picture:

Yes, after that and before the diffstat -- please check some examples in the list as Greg suggests.

Quoted 3 lines

Additionally, I suppose the base-commit tag should also be placed in 3 (above/below Signed-off-by), as it was added to the very end by git when generating the patch.

Where Git adds it should be fine :)

In fact, if you have a good Git commit, and you use the right flags, then Git can take care of essentially everything for you, i.e. you should not generally need to edit much (or anything at all), though you may or may not want to use some of its features, e.g. notes and branch descriptions. Please take a look at man git-format-patch.

Thanks!

Cheers,
Miguel