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

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] [day] [month] [year] [list]

Message-ID: <20241002022749.390836-2-paddymills@proton.me>
Date: Wed, 02 Oct 2024 02:29:03 +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>, Hridesh MG <hridesh699@...il.com>
Subject: [PATCH v5 2/2] checkpatch: warn on known non-plural rust doc headers and empty doc comments

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@...ton.me>
Co-developed-by: Hridesh MG <hridesh699@...il.com>
Suggested-by: Miguel Ojeda <ojeda@...nel.org>
Suggested-by: Trevor 
Gross <tmgross@...ch.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


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