| 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
| ||
|
Message-ID: <20260113214039.33999-1-foster.ryan.r@gmail.com>
Date: Tue, 13 Jan 2026 13:40:39 -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 1/2] 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
>From 4847892d292946caaf268a9f37b116394709c987 Mon Sep 17 00:00:00 2001
From: Ryan Foster <foster.ryan.r@...il.com>
Date: Tue, 13 Jan 2026 13:09:13 -0800
Subject: [PATCH 2/2] 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
Powered by blists - more mailing lists