[PATCH v5 1/2] docs: rust: make section names plural

[PATCH v5 1/2] docs: rust: make section names plural

[Patrick Miller]

[-- Attachment #1: Type: text/plain, Size: 2211 bytes --]

Fixes existing rust documentation section headers to be use plural names.

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
---
 rust/kernel/init.rs     | 2 +-
 rust/kernel/list/arc.rs | 2 +-
 rust/kernel/sync/arc.rs | 2 +-
 rust/macros/lib.rs      | 2 +-
 4 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/rust/kernel/init.rs b/rust/kernel/init.rs
index a17ac8762d8f..98889ddf9828 100644
--- a/rust/kernel/init.rs
+++ b/rust/kernel/init.rs
@@ -746,7 +746,7 @@ macro_rules! try_init {
 /// Asserts that a field on a struct using `#[pin_data]` is marked with `#[pin]` ie. that it is
 /// structurally pinned.
 ///
-/// # Example
+/// # Examples
 ///
 /// This will succeed:
 /// ```
diff --git a/rust/kernel/list/arc.rs b/rust/kernel/list/arc.rs
index d801b9dc6291..611ce07cd290 100644
--- a/rust/kernel/list/arc.rs
+++ b/rust/kernel/list/arc.rs
@@ -4
64,7 +464,7 @@ impl<T, U, const ID: u64> core::ops::DispatchFromDyn<ListArc<U, ID>> for ListArc
 
 /// A utility for tracking whether a [`ListArc`] exists using an atomic.
 ///
-/// # Invariant
+/// # Invariants
 ///
 /// If the boolean is `false`, then there is no [`ListArc`] for this value.
 #[repr(transparent)]
diff --git a/rust/kernel/sync/arc.rs b/rust/kernel/sync/arc.rs
index 3021f30fd822..3d3c100b0c0d 100644
--- a/rust/kernel/sync/arc.rs
+++ b/rust/kernel/sync/arc.rs
@@ -436,7 +436,7 @@ fn from(item: Pin<UniqueArc<T>>) -> Self {
 /// There are no mutable references to the underlying [`Arc`], and it remains valid for the
 /// lifetime of the [`ArcBorrow`] instance.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```
 /// use kernel::sync::{Arc, ArcBorrow};
diff --git a/rust/macros/lib.rs b/rust/macros/lib.rs
index a626b1145e5c..3879e1162866 100644
--- a/rust/macros/lib.rs
+++ b/rust/macros/lib.rs
@@ -307,7 +307,7 @@ pub fn pinned_drop(args: TokenStream, in
put: TokenStream) -> TokenStream {
 /// literals (lifetimes and documentation strings are not supported). There is a difference in
 /// supported modifiers as well.
 ///
-/// # Example
+/// # Examples
 ///
 /// ```ignore
 /// use kernel::macro::paste;
-- 
2.46.2


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 249 bytes --]

[PATCH v5 2/2] checkpatch: warn on known non-plural rust doc headers and empty doc comments

[Patrick Miller]

[-- Attachment #1: Type: text/plain, Size: 3556 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.

This revision also merges Hridesh MG's [1] patch to check for consecutive
empty doc comments. This checks and warns against consecutive empty `///`
lines in rust files.

[1]: https://lore.kernel.org/rust-for-linux/CALiyAo=ZdFy0bR03NndODmE7vP_JRzxs52-z=iXKQbO_Z6rtYg@mail.gmail.com/T/#u

Signed-off-by: Patrick Miller <paddymills@proton.me>
Co-developed-by: Hridesh MG <hridesh699@gmail.com>
Suggested-by: Miguel Ojeda <ojeda@kernel.org>
Suggested-by: Trevor 
Gross <tmgross@umich.edu>
Link: https://github.com/Rust-for-Linux/linux/issues/1110
Link: https://github.com/Rust-for-Linux/linux/issues/1109

---
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/da34f89c-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: https://lore.kernel.org/rust-for-linux/20240914181618.837227-2-paddymills@proton.me/
  - 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
v5:
  - merged Hridesh MG's patch[2] to check against consecutive rustdoc comments
  - revised Hridesh MG's
 patch to match against $prevrawline being new
      or existing
  - added fix to Hridesh MG's patch

[2]: https://lore.kernel.org/rust-for-linux/CALiyAo=ZdFy0bR03NndODmE7vP_JRzxs52-z=iXKQbO_Z6rtYg@mail.gmail.com/T/#m5afd633dc96ba366bbfd3d168c43d3a2a53b9198

 scripts/checkpatch.pl | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/scripts/checkpatch.pl b/scripts/checkpatch.pl
index 39032224d504..080b0eebde0a 100755
--- a/scripts/checkpatch.pl
+++ b/scripts/checkpatch.pl
@@ -3900,6 +3900,26 @@ 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|Error|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 for consecutive empty doc comment lines
+			if ($rawline =~ /^\+\s*\/\/\/$/ && $prevrawline =~ /^\+?\s*\/\/\/$/) {
+				if (WARN("RUST_DOC_EMPTY",
+				         "avoid using consecutive empty rustdoc comments\n" . $herecurr) &&
+				    $fix) {
+					fix_delete_line($fixlinenr, $rawline);
+				}
+			}
+		}
+
 # 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.2


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 249 bytes --]

Re: [PATCH v5 2/2] checkpatch: warn on known non-plural rust doc headers and empty doc comments

[Miguel Ojeda]

On Wed, Oct 2, 2024 at 4:29 AM Patrick Miller <paddymills@proton.me> wrote:
>
> Signed-off-by: Patrick Miller <paddymills@proton.me>

These tags are typically placed before your Signed-off-by (tags after
it are usually the ones added by the next person handling the patch,
i.e. the next Signed-off-by).

> Co-developed-by: Hridesh MG <hridesh699@gmail.com>

This tag requires a Signed-off-by -- please see:

    https://docs.kernel.org/process/submitting-patches.html#when-to-use-acked-by-cc-and-co-developed-by

> Suggested-by: Trevor
> Gross <tmgross@umich.edu>

It seems like the patch has been wrapped in a couple places.

>   - merged Hridesh MG's patch[2] to check against consecutive rustdoc comments
>   - revised Hridesh MG's
>  patch to match against $prevrawline being new
>       or existing
>   - added fix to Hridesh MG's patch

It may be clearer and simpler (for attribution purposes) to avoid
merging them, and instead add a check in each patch (you can still
rebase Hridesh's into yours on top, so that you add it inside the
`realfile` condition etc.).

I would also include Hridesh's cleanup here too if we are doing
everything here. Something like:

#1: clean A
#2: add check for A
#3: clean B
#4: add check for B

> +# checks for rust files

We already have other checks for Rust files that are shared with other
languages. Perhaps we can be slightly more clear with "checks for Rust
files (only)" or "Rust-only checks" or "checks that only apply to Rust
files"?

Thanks!

Cheers,
Miguel

Re: [PATCH v5 2/2] checkpatch: warn on known non-plural rust doc headers and empty doc comments

[Joe Perches]

On Wed, 2024-10-02 at 13:56 +0200, Miguel Ojeda wrote:
> We already have other checks for Rust files that are shared with other
> languages. Perhaps we can be slightly more clear with "checks for Rust
> files (only)" or "Rust-only checks" or "checks that only apply to Rust
> files"?

I'll get this sorted in the next week or so
and forwarded on.

Re: [PATCH v5 2/2] checkpatch: warn on known non-plural rust doc headers and empty doc comments

[Hridesh Mg]

02-Oct-2024 5:26:15 pm Miguel Ojeda <miguel.ojeda.sandonis@gmail.com>:
> I would also include Hridesh's cleanup here too if we are doing
> everything here. Something like:
>
> #1: clean A
> #2: add check for A
> #3: clean B
> #4: add check for B

In this case, I suppose it makes more sense to use the From: tag to signify ownership than Co-developed-by since the latter is used when multiple people work on the same patch according to https://docs.kernel.org/process/submitting-patches.html#when-to-use-acked-by-cc-and-co-developed-by

Re: [PATCH v5 2/2] checkpatch: warn on known non-plural rust doc headers and empty doc comments

[Miguel Ojeda]

On Wed, Oct 2, 2024 at 2:31 PM Hridesh Mg <hridesh699@gmail.com> wrote:
>
> In this case, I suppose it makes more sense to use the From: tag to signify ownership than Co-developed-by since the latter is used when multiple people work on the same patch according to https://docs.kernel.org/process/submitting-patches.html#when-to-use-acked-by-cc-and-co-developed-by

Definitely, that is what I meant by the attribution part. If Patrick
carries your patch (applies it and sends it on your behalf), then Git
will add it automatically.

Cheers,
Miguel

Re: [PATCH v5 1/2] docs: rust: make section names plural

[Miguel Ojeda]

On Wed, Oct 2, 2024 at 4:28 AM Patrick Miller <paddymills@proton.me> wrote:
>
> Fixes existing rust documentation section headers to be use plural names.
>
> 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

Applied to `rust-next` -- thanks!

    [ Removed the `init` one that doesn't apply anymore and
      reworded slightly. - Miguel ]

For context: https://lore.kernel.org/rust-for-linux/CANiq72nhNmLMdFTzpSQSxxMLanFA7Od6tBZ+3CrVERv9Spou5Q@mail.gmail.com/

Cheers,
Miguel