[PATCH] rust: update dbg macro outputs in docs

[PATCH] rust: update dbg macro outputs in docs

[Deepak Thukral]

Hi,

This patch updates outdated examples for `dbg!` macro.

Signed-off-by: Deepak Thukral <iapain@gmail.com>
---
 rust/kernel/std_vendor.rs | 22 +++++++++++-----------
 1 file changed, 11 insertions(+), 11 deletions(-)

diff --git a/rust/kernel/std_vendor.rs b/rust/kernel/std_vendor.rs
index 67bf9d37d..464b2c4b5 100644
--- a/rust/kernel/std_vendor.rs
+++ b/rust/kernel/std_vendor.rs
@@ -16,7 +16,7 @@
 /// let a = 2;
 /// # #[allow(clippy::dbg_macro)]
 /// let b = dbg!(a * 2) + 1;
-/// //      ^-- prints: [src/main.rs:2] a * 2 = 4
+/// //      ^-- prints: [src/main.rs:2:9] a * 2 = 4
 /// assert_eq!(b, 5);
 /// ```
 ///
@@ -65,7 +65,7 @@
 /// This prints to the kernel log:
 ///
 /// ```text,ignore
-/// [src/main.rs:4] n.checked_sub(4) = None
+/// [src/main.rs:4:8] n.checked_sub(4) = None
 /// ```
 ///
 /// Naive factorial implementation:
@@ -88,15 +88,15 @@
 /// This prints to the kernel log:
 ///
 /// ```text,ignore
-/// [src/main.rs:3] n <= 1 = false
-/// [src/main.rs:3] n <= 1 = false
-/// [src/main.rs:3] n <= 1 = false
-/// [src/main.rs:3] n <= 1 = true
-/// [src/main.rs:4] 1 = 1
-/// [src/main.rs:5] n * factorial(n - 1) = 2
-/// [src/main.rs:5] n * factorial(n - 1) = 6
-/// [src/main.rs:5] n * factorial(n - 1) = 24
-/// [src/main.rs:11] factorial(4) = 24
+/// [src/main.rs:3:8] n <= 1 = false
+/// [src/main.rs:3:8] n <= 1 = false
+/// [src/main.rs:3:8] n <= 1 = false
+/// [src/main.rs:3:8] n <= 1 = true
+/// [src/main.rs:4:9] 1 = 1
+/// [src/main.rs:5:9] n * factorial(n - 1) = 2
+/// [src/main.rs:5:9] n * factorial(n - 1) = 6
+/// [src/main.rs:5:9] n * factorial(n - 1) = 24
+/// [src/main.rs:11:1] factorial(4) = 24
 /// ```
 ///
 /// The `dbg!(..)` macro moves the input:
-- 
2.39.3

Re: [PATCH] rust: update dbg macro outputs in docs

[Miguel Ojeda]

On Fri, Oct 4, 2024 at 12:17 AM Deepak Thukral <iapain@gmail.com> wrote:
>
> Hi,
>
> This patch updates outdated examples for `dbg!` macro.

Thanks for the patch!

A few notes on the commit message:

  - It should explain what the change is and why it is done --
currently it just says "outdated examples", without mentioning why
they are updated or what the change is.

  - Please read the notes in the GitHub issue to know what tags you
should add above the Signed-off-by one.

  - Commit messages should not start with "Hi," (you can, however, add
that kind of text/message below the `---` line and it will not go into
the commit) and they should generally be written using the imperative
mood.

  - Please take a look at
https://docs.kernel.org/process/submitting-patches.html -- most of
this is described there.

> -/// //      ^-- prints: [src/main.rs:2] a * 2 = 4
> +/// //      ^-- prints: [src/main.rs:2:9] a * 2 = 4

In terms of the content, this looks OK. However, a couple questions:

  - Did you copy the output from the standard library? Did you
double-check if our output looks like that (in terms of the column
number)? Mentioning this in the commit message is a good idea.

  - The GitHub issue mentioned the column numbers, so this is good;
however, did you compare this file with the standard library one to
check if other changes/improvements could be imported?

Thanks!

Cheers,
Miguel

Re: [PATCH] rust: update dbg macro outputs in docs

[Deepak]

Hi,

Thanks for the quick review. I will rework on this patch.

>   - It should explain what the change is and why it is done --
> currently it just says "outdated examples", without mentioning why
> they are updated or what the change is.

Sorry for not being outward with my commit message and thanks for
mentioning this. I will rework on that.

>   - Please read the notes in the GitHub issue to know what tags you
> should add above the Signed-off-by one.

I have clearly missed that. I will include this in next patch version

>   - Commit messages should not start with "Hi," (you can, however, add
> that kind of text/message below the `---` line and it will not go into
> the commit) and they should generally be written using the imperative
> mood.

Noted

>   - Did you copy the output from the standard library? Did you
> double-check if our output looks like that (in terms of the column
> number)? Mentioning this in the commit message is a good idea.

Output wasn't copied from std lib, instead it was adjusted to reflect examples.

>   - The GitHub issue mentioned the column numbers, so this is good;
> however, did you compare this file with the standard library one to
> check if other changes/improvements could be imported?

I did compare `std_vendor.rs` with std lib and I didn't observe any
change in the code. As mentioned in the GH issue, only inconsistency
which I did notice as well was the missing column number in outputs.

Cheers,
Deepak

Re: [PATCH] rust: update dbg macro outputs in docs

[Miguel Ojeda]

On Fri, Oct 4, 2024 at 11:00 AM Deepak <iapain@gmail.com> wrote:
>
> Sorry for not being outward with my commit message and thanks for
> mentioning this. I will rework on that.

No need to apologize -- it is all good. v2 looks fine :)

Cheers,
Miguel

Re: [PATCH] rust: update dbg macro outputs in docs

[Deepak]

> No need to apologize -- it is all good. v2 looks fine :)

Thanks! Very kind of you :)

Cheers,
Deepak