linux-kernel - [PATCH v2] checkpatch: warn on Rust comments with rustdoc links above items

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

Message-ID: <20260113211025.637889-1-foster.ryan.r@gmail.com>
Date: Tue, 13 Jan 2026 13:10:25 -0800
From: Ryan Foster <foster.ryan.r@...il.com>
To: joe@...ches.com
Cc: foster.ryan.r@...il.com,
	linux-kernel@...r.kernel.org,
	ojeda@...nel.org,
	rust-for-linux@...r.kernel.org
Subject: [PATCH v2] checkpatch: warn on Rust comments with rustdoc links above items

Add a check to emit a warning when a `//` comment containing rustdoc
link patterns (like [`Foo`]) appears directly above a Rust item
declaration. This likely indicates the comment should use `///`
documentation syntax instead.

The check uses heuristics to reduce false positives:
- Only triggers on comments with rustdoc link syntax [`...`]
- Excludes doc comments (/// and //!)
- Excludes special comments (SAFETY:, TODO:, FIXME:, NOTE:, INVARIANT:,
  INVARIANTS:, NB:, CAST:, GUARANTEE:, GUARANTEES:, PANIC:, OVERFLOW:,
  BOUNDS:, etc.)
- Only warns when directly above a Rust item (fn, struct, enum, etc.)

Examples that trigger the warning:
    // Returns a reference to the underlying [`Table`].
    fn table(&self) -> &Table { }

Examples that do NOT trigger:
    // SAFETY: The `ptr` is guaranteed by the C code to be valid.
    unsafe fn foo() { }

    // TODO: fix this later
    fn bar() { }

    // Regular comment without rustdoc links
    fn baz() { }

v2: Apply suggestions from Joe Perches:
    - Exclude /// and //! doc comments using negative lookahead
    - Add more special comment tags found in tree (NB:, INVARIANTS:,
      CAST:, GUARANTEES:, PANIC:, OVERFLOW:, GUARANTEE:, BOUNDS:)

Link: https://github.com/Rust-for-Linux/linux/issues/1157
Suggested-by: Miguel Ojeda <ojeda@...nel.org>
Suggested-by: Joe Perches <joe@...ches.com>
Signed-off-by: Ryan Foster <foster.ryan.r@...il.com>
---
 scripts/checkpatch.pl | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/scripts/checkpatch.pl b/scripts/checkpatch.pl
index 1b09b9194c94..a5a462827aba 100755
--- a/scripts/checkpatch.pl
+++ b/scripts/checkpatch.pl
@@ -3926,12 +3926,12 @@ sub process {
 # Warn when a // comment that looks like documentation (contains rustdoc
 # link patterns like [`Foo`]) appears directly above a Rust item.
 		if ($realfile =~ /\.rs$/ &&
-		    $rawline =~ /^\+(\s*)\/\/\s+(.*)$/) {
-			my $comment_text = $2;
+		    $rawline =~ m{^\+\s*//(?![/!])(.*)}s) {
+			my $comment_text = $1;
 			# Check if this looks like a doc comment (contains rustdoc link patterns)
 			# and is NOT a special comment like SAFETY:, TODO:, FIXME:, etc.
 			if ($comment_text =~ /\[`[^\]]+`\]/ &&
-			    $comment_text !~ /^\s*(?:SAFETY|TODO|FIXME|NOTE|XXX|HACK|BUG|INVARIANT):/) {
+			    $comment_text !~ /^\s*(?:SAFETY|TODO|FIXME|NOTE|XXX|HACK|BUG|INVARIANTS?|NB|CAST|GUARANTEES?|PANIC|OVERFLOW|BOUNDS):/) {
 				# Check if next line starts a Rust item
 				my $nextline = $rawlines[$linenr];
 				if (defined($nextline) &&
-- 
2.52.0