linux-kernel - [PATCH v4 2/2] 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 for Android: free password hash cracker in your pocket

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

Message-ID: <20240914181618.837227-2-paddymills@proton.me>
Date: Sat, 14 Sep 2024 18:16:56 +0000
From: Patrick Miller <paddymills@...ton.me>
To: Andy Whitcroft <apw@...onical.com>, Joe Perches <joe@...ches.com>, Dwaipayan Ray <dwaipayanray1@...il.com>, Lukas Bulwahn <lukas.bulwahn@...il.com>, Miguel Ojeda <ojeda@...nel.org>, Alex Gaynor <alex.gaynor@...il.com>, Wedson Almeida Filho <wedsonaf@...il.com>, Boqun Feng <boqun.feng@...il.com>, Gary Guo <gary@...yguo.net>, Björn Roy Baron <bjorn3_gh@...tonmail.com>, Benno Lossin <benno.lossin@...ton.me>, Andreas Hindborg <a.hindborg@...sung.com>, Alice Ryhl <aliceryhl@...gle.com>, Trevor Gross <tmgross@...ch.edu>, linux-kernel@...r.kernel.org, rust-for-linux@...r.kernel.org
Cc: Patrick Miller <paddymills@...ton.me>
Subject: [PATCH v4 2/2] checkpatch: warn on known non-plural rust doc headers

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@...ton.me>
Suggested-by: Miguel Ojeda <ojeda@...nel.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@...ton.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


Download attachment "signature.asc" of type "application/pgp-signature" (250 bytes)