* Re: [PATCH v3 2/2] checkpatch: warn on known non-plural rust doc headers
2024-09-12 19:56 [PATCH v3 2/2] checkpatch: warn on known non-plural rust doc headers Patrick Miller
@ 2024-09-13 7:33 ` Alice Ryhl
2024-09-13 19:21 ` Joe Perches
2024-09-13 11:30 ` Benno Lossin
2024-09-14 18:16 ` [PATCH v4 " Patrick Miller
2 siblings, 1 reply; 6+ messages in thread
From: Alice Ryhl @ 2024-09-13 7:33 UTC (permalink / raw)
To: Patrick Miller
Cc: a.hindborg, alex.gaynor, apw, benno.lossin, bjorn3_gh, boqun.feng,
dwaipayanray1, gary, joe, linux-kernel, lukas.bulwahn, ojeda,
rust-for-linux, tmgross, wedsonaf
On Thu, Sep 12, 2024 at 9:57 PM Patrick Miller <paddymills@proton.me> wrote:
>
> Adds a check for documentation in rust file. Warns if certain known
> documentation headers are not plural.
>
> The rust maintainers prefer document headers to be plural. This is to enforce
> consistency among the documentation as well as to protect against errors when
> additions are made. For example, if the header said "Example" because there was
> only 1 example, if a second example was added, making the header plural could
> easily be missed and the maintainers prefer to not have to remind people to fix
> their documentation.
>
> Link: https://github.com/Rust-for-Linux/linux/issues/1110
>
> v1: https://lore.kernel.org/rust-for-linux/2024090628-bankable-refusal-5f20@gregkh/T/#t
> v2: https://lore.kernel.org/rust-for-linux/92be0b48-cde9-4241-8ef9-7fe4d7c42466@proton.me/T/#t
> - fixed whitespace that was formatted due to editor settings
> v3:
> - move && to previous line and remove whitespace in WARN per Joe Perches
> - reformat following C coding style
> ---
> scripts/checkpatch.pl | 7 ++++
> +++
> 1 file changed, 7 insertions(+)
This is missing your Signed-off-by and the changelog should be below
the --- line so it doesn't get included in the changelog when applied.
The change itself looks good to me.
Alice
>
> diff --git a/scripts/checkpatch.pl b/scripts/checkpatch.pl
> index 39032224d504..5b18246ad511 100755
> --- a/scripts/checkpatch.pl
> +++ b/scripts/checkpatch.pl
> @@ -3900,6 +3900,13 @@ sub process {
> "Avoid using '.L' prefixed local symbol names for denoting a range of code via 'SYM_*_START/END' annotations; see Documentation/core-api/asm-annotations.rst\n" . $herecurr);
> }
>
> +# check that document section headers are plural in rust files
> + if ($realfile =~ /\.rs$/ &&
> + $rawline =~ /^\+\s*\/\/\/\s+#+\s+(Example|Invariant|Guarantee|Panic)\s*$/) {
> + WARN("RUST_DOC_HEADER",
> + "Rust doc headers should be plural\n" . $herecurr);
> + }
> +
> # check we are in a valid source file C or perl if not then ignore this hunk
> next if ($realfile !~ /\.(h|c|pl|dtsi|dts)$/);
>
> --
> 2.46.0
>
^ permalink raw reply [flat|nested] 6+ messages in thread* Re: [PATCH v3 2/2] checkpatch: warn on known non-plural rust doc headers
2024-09-13 7:33 ` Alice Ryhl
@ 2024-09-13 19:21 ` Joe Perches
2024-09-13 19:34 ` Benno Lossin
0 siblings, 1 reply; 6+ messages in thread
From: Joe Perches @ 2024-09-13 19:21 UTC (permalink / raw)
To: Alice Ryhl, Patrick Miller
Cc: a.hindborg, alex.gaynor, apw, benno.lossin, bjorn3_gh, boqun.feng,
dwaipayanray1, gary, linux-kernel, lukas.bulwahn, ojeda,
rust-for-linux, tmgross, wedsonaf
On Fri, 2024-09-13 at 09:33 +0200, Alice Ryhl wrote:
> On Thu, Sep 12, 2024 at 9:57 PM Patrick Miller <paddymills@proton.me> wrote:
> >
> > Adds a check for documentation in rust file. Warns if certain known
> > documentation headers are not plural.
> >
> > The rust maintainers prefer document headers to be plural. This is to enforce
> > consistency among the documentation as well as to protect against errors when
> > additions are made. For example, if the header said "Example" because there was
> > only 1 example, if a second example was added, making the header plural could
> > easily be missed and the maintainers prefer to not have to remind people to fix
> > their documentation.
> >
> > Link: https://github.com/Rust-for-Linux/linux/issues/1110
> >
> > v1: https://lore.kernel.org/rust-for-linux/2024090628-bankable-refusal-5f20@gregkh/T/#t
> > v2: https://lore.kernel.org/rust-for-linux/92be0b48-cde9-4241-8ef9-7fe4d7c42466@proton.me/T/#t
> > - fixed whitespace that was formatted due to editor settings
> > v3:
> > - move && to previous line and remove whitespace in WARN per Joe Perches
> > - reformat following C coding style
> > ---
> > scripts/checkpatch.pl | 7 ++++
> > +++
> > 1 file changed, 7 insertions(+)
>
> This is missing your Signed-off-by and the changelog should be below
> the --- line so it doesn't get included in the changelog when applied.
[]
> > diff --git a/scripts/checkpatch.pl b/scripts/checkpatch.pl
[]
> > @@ -3900,6 +3900,13 @@ sub process {
> > "Avoid using '.L' prefixed local symbol names for denoting a range of code via 'SYM_*_START/END' annotations; see Documentation/core-api/asm-annotations.rst\n" . $herecurr);
> > }
> >
> > +# check that document section headers are plural in rust files
> > + if ($realfile =~ /\.rs$/ &&
> > + $rawline =~ /^\+\s*\/\/\/\s+#+\s+(Example|Invariant|Guarantee|Panic)\s*$/) {
> > + WARN("RUST_DOC_HEADER",
> > + "Rust doc headers should be plural\n" . $herecurr);
While OK my suggestion would be to add a $fix option
and be case insensitive
if ($realfile =~ /\.rs$/ &&
$rawline =~ /^\+\s*\/\/\/\s+#+\s+(Example|Invariant|Guarantee|Panic)\s*$/i) {
if (WARN("RUST_DOC_HEADER",
"Rust doc header '$1' should be plural\n" . $herecurr) &&
$fix) {
$fixed[$fixlinenr] = s/\b$1\b/ucfirst(lc($1))/e;
}
And if there are going to be more rust specific tests,
there should be a rust specific block to avoid continual
tests of $realfile =~ /\.rs$/
^ permalink raw reply [flat|nested] 6+ messages in thread* Re: [PATCH v3 2/2] checkpatch: warn on known non-plural rust doc headers
2024-09-13 19:21 ` Joe Perches
@ 2024-09-13 19:34 ` Benno Lossin
0 siblings, 0 replies; 6+ messages in thread
From: Benno Lossin @ 2024-09-13 19:34 UTC (permalink / raw)
To: Joe Perches, Alice Ryhl, Patrick Miller
Cc: a.hindborg, alex.gaynor, apw, bjorn3_gh, boqun.feng,
dwaipayanray1, gary, linux-kernel, lukas.bulwahn, ojeda,
rust-for-linux, tmgross, wedsonaf
On 13.09.24 21:21, Joe Perches wrote:
> On Fri, 2024-09-13 at 09:33 +0200, Alice Ryhl wrote:
>> On Thu, Sep 12, 2024 at 9:57 PM Patrick Miller <paddymills@proton.me> wrote:
>>> @@ -3900,6 +3900,13 @@ sub process {
>>> "Avoid using '.L' prefixed local symbol names for denoting a range of code via 'SYM_*_START/END' annotations; see Documentation/core-api/asm-annotations.rst\n" . $herecurr);
>>> }
>>>
>>> +# check that document section headers are plural in rust files
>>> + if ($realfile =~ /\.rs$/ &&
>>> + $rawline =~ /^\+\s*\/\/\/\s+#+\s+(Example|Invariant|Guarantee|Panic)\s*$/) {
@Patrick, could you also add `Error` to this list?
>>> + WARN("RUST_DOC_HEADER",
>>> + "Rust doc headers should be plural\n" . $herecurr);
>
> While OK my suggestion would be to add a $fix option
> and be case insensitive
>
> if ($realfile =~ /\.rs$/ &&
> $rawline =~ /^\+\s*\/\/\/\s+#+\s+(Example|Invariant|Guarantee|Panic)\s*$/i) {
> if (WARN("RUST_DOC_HEADER",
> "Rust doc header '$1' should be plural\n" . $herecurr) &&
> $fix) {
> $fixed[$fixlinenr] = s/\b$1\b/ucfirst(lc($1))/e;
> }
>
> And if there are going to be more rust specific tests,
> there should be a rust specific block to avoid continual
> tests of $realfile =~ /\.rs$/
Yes please, we're already planning more checks.
---
Cheers,
Benno
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH v3 2/2] checkpatch: warn on known non-plural rust doc headers
2024-09-12 19:56 [PATCH v3 2/2] checkpatch: warn on known non-plural rust doc headers Patrick Miller
2024-09-13 7:33 ` Alice Ryhl
@ 2024-09-13 11:30 ` Benno Lossin
2024-09-14 18:16 ` [PATCH v4 " Patrick Miller
2 siblings, 0 replies; 6+ messages in thread
From: Benno Lossin @ 2024-09-13 11:30 UTC (permalink / raw)
To: Patrick Miller, a.hindborg, alex.gaynor, aliceryhl, apw,
bjorn3_gh, boqun.feng, dwaipayanray1, gary, joe, linux-kernel,
lukas.bulwahn, ojeda, rust-for-linux, tmgross, wedsonaf
On 12.09.24 21:56, Patrick Miller wrote:
> Adds a check for documentation in rust file. Warns if certain known
> documentation headers are not plural.
>
> The rust maintainers prefer document headers to be plural. This is to enforce
> consistency among the documentation as well as to protect against errors when
> additions are made. For example, if the header said "Example" because there was
> only 1 example, if a second example was added, making the header plural could
> easily be missed and the maintainers prefer to not have to remind people to fix
> their documentation.
Nit: this is wrapped to 80 chars, but a maximum of 75 columns is
preferred. I usually use 72.
---
Cheers,
Benno
> Link: https://github.com/Rust-for-Linux/linux/issues/1110
>
> v1: https://lore.kernel.org/rust-for-linux/2024090628-bankable-refusal-5f20@gregkh/T/#t
> v2: https://lore.kernel.org/rust-for-linux/92be0b48-cde9-4241-8ef9-7fe4d7c42466@proton.me/T/#t
> - fixed whitespace that was formatted due to editor settings
> v3:
> - move && to previous line and remove whitespace in WARN per Joe Perches
> - reformat following C coding style
> ---
> scripts/checkpatch.pl | 7 ++++
> +++
> 1 file changed, 7 insertions(+)
>
> diff --git a/scripts/checkpatch.pl b/scripts/checkpatch.pl
> index 39032224d504..5b18246ad511 100755
> --- a/scripts/checkpatch.pl
> +++ b/scripts/checkpatch.pl
> @@ -3900,6 +3900,13 @@ sub process {
> "Avoid using '.L' prefixed local symbol names for denoting a range of code via 'SYM_*_START/END' annotations; see Documentation/core-api/asm-annotations.rst\n" . $herecurr);
> }
>
> +# check that document section headers are plural in rust files
> + if ($realfile =~ /\.rs$/ &&
> + $rawline =~ /^\+\s*\/\/\/\s+#+\s+(Example|Invariant|Guarantee|Panic)\s*$/) {
> + WARN("RUST_DOC_HEADER",
> + "Rust doc headers should be plural\n" . $herecurr);
> + }
> +
> # check we are in a valid source file C or perl if not then ignore this hunk
> next if ($realfile !~ /\.(h|c|pl|dtsi|dts)$/);
>
> --
> 2.46.0
>
^ permalink raw reply [flat|nested] 6+ messages in thread* [PATCH v4 2/2] checkpatch: warn on known non-plural rust doc headers
2024-09-12 19:56 [PATCH v3 2/2] checkpatch: warn on known non-plural rust doc headers Patrick Miller
2024-09-13 7:33 ` Alice Ryhl
2024-09-13 11:30 ` Benno Lossin
@ 2024-09-14 18:16 ` Patrick Miller
2 siblings, 0 replies; 6+ messages in thread
From: Patrick Miller @ 2024-09-14 18:16 UTC (permalink / raw)
To: Andy Whitcroft, Joe Perches, Dwaipayan Ray, Lukas Bulwahn,
Miguel Ojeda, Alex Gaynor, Wedson Almeida Filho, Boqun Feng,
Gary Guo, Björn Roy Baron, Benno Lossin, Andreas Hindborg,
Alice Ryhl, Trevor Gross, linux-kernel, rust-for-linux
Cc: Patrick Miller
[-- Attachment #1: Type: text/plain, Size: 2342 bytes --]
Adds a check for documentation in rust file. Warns if certain known
documentation headers are not plural.
The rust maintainers prefer document headers to be plural. This is to
enforce consistency among the documentation as well as to protect against
errors when additions are made. For example, if the header said "Example"
because there was only 1 example, if a second example was added, making
the header plural could easily be missed and the maintainers prefer to
not have to remind people to fix their documentation.
Signed-off-by: Patrick Miller <paddymills@proton.me>
Suggested-by: Miguel Ojeda <ojeda@kernel.org>
Link: https://github.com/Rust-for-Linux/linux/issues/1110
---
v1: https://lore.kernel.org/rust-for-linux/2024090628-bankable-refusal-5f20@gregkh/T/#t
v2: https://lore.kernel.org/rust-for-linux/92be0b48-cde9-4241-8ef9-7fe4d7c42466@proton.me/T/#t
- fixed whitespace that was formatted due to editor settings
v3: https://lore.kernel.org/rust-for-linux/da34f89
c-f94c-43aa-946c-57fec3597974@proton.me/T/#t
- move && to previous line and remove whitespace in WARN per Joe Perches
- reformat following C coding style
v4:
- add @fix option (credit: Joe Perches)
- add Error to list of checked section headers
- make check for rust file its own if statement because more rust
checks are planned
scripts/checkpatch.pl | 12 ++++++++++++
1 file changed, 12 insertions(+)
diff --git a/scripts/checkpatch.pl b/scripts/checkpatch.pl
index 39032224d504..d4711cd14b36 100755
--- a/scripts/checkpatch.pl
+++ b/scripts/checkpatch.pl
@@ -3900,6 +3900,18 @@ sub process {
"Avoid using '.L' prefixed local symbol names for denoting a range of code via 'SYM_*_START/END' annotations; see Documentation/core-api/asm-annotations.rst\n" . $herecurr);
}
+# checks for rust files
+ if ($realfile =~ /\.rs$/) {
+# check that document section headers are plural in rust files
+ if ($rawline =~ /^\+\s*\/\/\/\s+#+\s+(Example|Er
ror|Guarantee|Invariant|Panic)\s*$/i) {
+ if (WARN("RUST_DOC_HEADER",
+ "Rust doc section names should be plural\n" . $herecurr) &&
+ $fix) {
+ $fixed[$fixlinenr] = s/\b$1\b/ucfirst(lc($1))/e;
+ }
+ }
+ }
+
# check we are in a valid source file C or perl if not then ignore this hunk
next if ($realfile !~ /\.(h|c|pl|dtsi|dts)$/);
--
2.46.0
[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 249 bytes --]
^ permalink raw reply related [flat|nested] 6+ messages in thread