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

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

[Sai Vishnu M]

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

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

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..41404c1e17b3 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 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
link: https://lore.kernel.org/rust-for-linux/20250530123129.31505-2-saivishnu725@gmail.com/

v2: removed reference to the variable entirely.
link: https://lore.kernel.org/rust-for-linux/20250601164939.5306-2-saivishnu725@gmail.com/

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

base-commit: 7a17bbc1d952057898cb0739e60665908fbb8c72
-- 
2.49.0

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

[Greg KH]

On Mon, Jun 02, 2025 at 02:01:20PM +0530, Sai Vishnu M wrote:
> From: Sai Vishnu M <saivishnu725@gmail.com>
> 
> Removed reference to internal variables in the comment of `IoMem`
> This avoids using private variable names in public documentation.
> 
> 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..41404c1e17b3 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 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
> link: https://lore.kernel.org/rust-for-linux/20250530123129.31505-2-saivishnu725@gmail.com/
> 
> v2: removed reference to the variable entirely.
> link: https://lore.kernel.org/rust-for-linux/20250601164939.5306-2-saivishnu725@gmail.com/
> 
> 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

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

[Sai Vishnu]

> 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!

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

[Greg KH]

On Mon, Jun 02, 2025 at 04:41:20PM +0530, Sai Vishnu wrote:
> > 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.

No, that is fine.

> 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

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

[Miguel Ojeda]

On Mon, Jun 2, 2025 at 1:11 PM Sai Vishnu <saivishnu725@gmail.com> wrote:
>
> 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.

> 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