linux-kernel - [PATCH] 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: Windows password security audit tool. GUI, reports in PDF.

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

Message-ID: <20260113202138.565332-1-foster.ryan.r@gmail.com>
Date: Tue, 13 Jan 2026 12:21:38 -0800
From: Ryan Foster <foster.ryan.r@...il.com>
To: linux-kernel@...r.kernel.org
Cc: rust-for-linux@...r.kernel.org,
	joe@...ches.com,
	ojeda@...nel.org,
	Ryan Foster <foster.ryan.r@...il.com>
Subject: [PATCH] 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 special comments (SAFETY:, TODO:, FIXME:, 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() { }

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

diff --git a/scripts/checkpatch.pl b/scripts/checkpatch.pl
index c0250244cf7a..1b09b9194c94 100755
--- a/scripts/checkpatch.pl
+++ b/scripts/checkpatch.pl
@@ -3922,6 +3922,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);
 		}
 
+# check for Rust comments that should likely be doc comments
+# 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;
+			# 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):/) {
+				# Check if next line starts a Rust item
+				my $nextline = $rawlines[$linenr];
+				if (defined($nextline) &&
+				    $nextline =~ /^\+\s*(?:pub(?:\s*\([^)]*\))?\s+)?(?:unsafe\s+)?(?:async\s+)?(?:fn|struct|enum|impl|trait|const|static|type|mod|use)\b/) {
+					WARN("RUST_COMMENT_NOT_DOC",
+					     "Comment with rustdoc link pattern may need '///' instead of '//'\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.52.0