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-next>] [day] [month] [year] [list]
Message-ID: <20240912195649.227878-1-paddymills@proton.me>
Date: Thu, 12 Sep 2024 19:56:57 +0000
From: Patrick Miller <paddymills@...ton.me>
To: a.hindborg@...sung.com, alex.gaynor@...il.com, aliceryhl@...gle.com, apw@...onical.com, benno.lossin@...ton.me, bjorn3_gh@...tonmail.com, boqun.feng@...il.com, dwaipayanray1@...il.com, gary@...yguo.net, joe@...ches.com, linux-kernel@...r.kernel.org, lukas.bulwahn@...il.com, ojeda@...nel.org, rust-for-linux@...r.kernel.org, tmgross@...ch.edu, wedsonaf@...il.com
Cc: Patrick Miller <paddymills@...ton.me>
Subject: [PATCH v3 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.

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:
  - move && to previous line and remove whitespace in WARN per Joe Perches
  - reformat following C coding style
---
 scripts/checkpatch.pl | 7 ++++
+++
 1 file changed, 7 insertions(+)

diff --git a/scripts/checkpatch.pl b/scripts/checkpatch.pl
index 39032224d504..5b18246ad511 100755
--- a/scripts/checkpatch.pl
+++ b/scripts/checkpatch.pl
@@ -3900,6 +3900,13 @@ 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);
 		}
 
+# check that document section headers are plural in rust files
+		if ($realfile =~ /\.rs$/ &&
+		    $rawline =~ /^\+\s*\/\/\/\s+#+\s+(Example|Invariant|Guarantee|Panic)\s*$/) {
+			WARN("RUST_DOC_HEADER",
+			     "Rust doc headers should be plural\n" . $herecurr);
+		}
+
 # 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)

Powered by blists - more mailing lists

Powered by Openwall GNU/*/Linux Powered by OpenVZ