[PATCH v6 2/4] checkpatch: warn on known non-plural rust doc headers

[Hridesh MG]

From: Patrick Miller <paddymills@xxxxxxxxx>

Add a check for documentation in rust files. Warn if certain known
documentation headers are not plural.

The rust maintainers prefer document headers to be plural. This is to
enforce consistency as well as to protect against errors when additions
are made. For instance, if a header says "Example" for a single example,
adding a second example may cause confusion. The maintainers wish to
avoid reminding users to update their documentation for such cases.

Suggested-by: Miguel Ojeda <ojeda@xxxxxxxxxx>
Link: https://github.com/Rust-for-Linux/linux/issues/1110
Signed-off-by: Patrick Miller <paddymills@xxxxxxxxx>
Signed-off-by: Hridesh MG <hridesh699@xxxxxxxxx>
---
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@xxxxxxxxx/T/#t
  - fixed whitespace that was formatted due to editor settings 
v3: https://lore.kernel.org/rust-for-linux/da34f89c-f94c-43aa-946c-57fec3597974@xxxxxxxxx/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@xxxxxxxxx/
  - 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: https://lore.kernel.org/rust-for-linux/20241002022749.390836-2-paddymills@xxxxxxxxx/
  - merged Hridesh MG's patch[1] to check against consecutive empty rustdoc comments
  - revised Hridesh MG's patch to match against $prevrawline being new
      or existing
  - added fix to Hridesh MG's patch
v6:
  - undid the merging of Hridesh MG's patch
  - revised opening comment to be more explicit per Miguel Ojeda
  - The --fix option was throwing an uninitialized variable error, fixed
    it and made it automatically convert the headers to plural.

[1]: https://lore.kernel.org/rust-for-linux/bf6544faba2b53ce901b2e031f3d944babcc7018.1727606659.git.hridesh699@xxxxxxxxx/
---
 scripts/checkpatch.pl | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/scripts/checkpatch.pl b/scripts/checkpatch.pl
index 4427572b2477..c390a9926cd5 100755
--- a/scripts/checkpatch.pl
+++ b/scripts/checkpatch.pl
@@ -3900,6 +3900,19 @@ 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 that only apply to Rust files
+		if ($realfile =~ /\.rs$/) {
+			# check that document section headers are plural
+			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) {
+					my $header = $1;
+					$fixed[$fixlinenr] =~ s/\b$header\b/ucfirst(lc($header)) . 's'/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.1