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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <088495172736416665325802594aeb6996159f9a.1728818976.git.hridesh699@gmail.com>
Date: Tue, 15 Oct 2024 21:21:37 +0530
From: Hridesh MG <hridesh699@...il.com>
To: rust-for-linux@...r.kernel.org,
	linux-kernel@...r.kernel.org
Cc: Andreas Hindborg <a.hindborg@...nel.org>,
	Boqun Feng <boqun.feng@...il.com>,
	Miguel Ojeda <ojeda@...nel.org>,
	Alex Gaynor <alex.gaynor@...il.com>,
	Gary Guo <gary@...yguo.net>,
	Björn Roy Baron <bjorn3_gh@...tonmail.com>,
	Benno Lossin <benno.lossin@...ton.me>,
	Alice Ryhl <aliceryhl@...gle.com>,
	Trevor Gross <tmgross@...ch.edu>,
	Andy Whitcroft <apw@...onical.com>,
	Joe Perches <joe@...ches.com>,
	Dwaipayan Ray <dwaipayanray1@...il.com>,
	Lukas Bulwahn <lukas.bulwahn@...il.com>,
	Hridesh MG <hridesh699@...il.com>,
	Jens Axboe <axboe@...nel.dk>,
	Wedson Almeida Filho <walmeida@...rosoft.com>,
	Valentin Obst <kernel@...entinobst.de>,
	Patrick Miller <paddymills@...ton.me>,
	Alex Mantel <alexmantel93@...lbox.org>,
	Matt Gilbride <mattgilbride@...gle.com>,
	Aswin Unnikrishnan <aswinunni01@...il.com>,
	Martin Rodriguez Reboredo <yakoyoku@...il.com>,
	FUJITA Tomonori <fujita.tomonori@...il.com>
Subject: [PATCH v6 2/4] checkpatch: warn on known non-plural rust doc headers

From: Patrick Miller <paddymills@...ton.me>

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@...nel.org>
Link: https://github.com/Rust-for-Linux/linux/issues/1110
Signed-off-by: Patrick Miller <paddymills@...ton.me>
Signed-off-by: Hridesh MG <hridesh699@...il.com>
---
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: https://lore.kernel.org/rust-for-linux/20241002022749.390836-2-paddymills@proton.me/
  - 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@gmail.com/
---
 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