checkpatch: warn on Rust comments with rustdoc links above items
Subsystems (2)
PATCH 1/1 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() { }--- scripts/checkpatch.pl | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+)
scripts/checkpatch.pl +20 -0
@@ -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)$/);
Signature · 1 line
2.52.0
Joe Perches
maintainerQuoted 4 lines · Ryan Foster
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.
[]
scripts/checkpatch.pl
Quoted 1 line
scripts/checkpatch.pl +0
-0
[]
scripts/checkpatch.pl sub process { · line 3929
Quoted 9 lines
scripts/checkpatch.pl +5
-0@@ -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+(.*)$/) {
No objection but maybe $rawline should be something like:
$rawline =~ m{^\+\s*//(?![/!])(.*)} {
my $comment_text = $1;etc...
scripts/checkpatch.pl sub process { · line 3934
Quoted 5 lines
scripts/checkpatch.pl +5
-0+ 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):/) {
[]
scripts/checkpatch.pl sub process { · line 3940
Quoted 6 lines
scripts/checkpatch.pl +6
-0+ # 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);
[]
Random grep results:
Note: seems to be used as well
What about NB: and INVARIANTS ?
$ git grep -i -P -oh '^\s*\/\/(?![/!])\s*(?:SAFETY|TODO|FIXME|NOTE|XXX|HACK|BUG|INVARIANT|\w+):' -- '*.rs'| sed -r 's/^\s+//' | sort | uniq -c | sort -rn
2081 // SAFETY:
183 // INVARIANT:
42 // TODO:
33 // CAST:
11 // GUARANTEES:
9 // NOTE:
8 // PANIC:
7 // Note:
6 // TIMEOUT:
6 // https:
3 // Type:
3 // TraitItem:
3 // Pat:
3 // OVERFLOW:
3 // Item:
3 // ImplItem:
3 // GUARANTEE:
3 // ForeignItem:
3 // FIXME:
3 // Expr:
3 // Example:
2 // NB:
2 // core:
2 // Author:
1 // u64:
1 // sym:
1 // std:
1 // span:
1 // sizeof:
1 // Reference:
1 // out:
1 // Object:
1 // namely:
1 // INVARIANTS:
1 // in:
1 // FieldMutability:
1 // Chip:
1 // BOUNDS:
1 // 2:
1 // 1:PATCH v2 1/1 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:)
--- scripts/checkpatch.pl | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-)
scripts/checkpatch.pl +3 -3
@@ -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) &&
Signature · 1 line
2.52.0
Joe Perches
maintainerQuoted 4 lines · Ryan Foster
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.
You sent a delta patch from v1 as v2.
Please send the entire patch instead.
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() { }--- scripts/checkpatch.pl | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+)
scripts/checkpatch.pl +20 -0
@@ -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)$/);
Signature · 48 lines
2.52.0 From 4847892d292946caaf268a9f37b116394709c987 Mon Sep 17 00:00:00 2001 From: Ryan Foster <[email protected]> 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 <[email protected]> Suggested-by: Joe Perches <[email protected]> Signed-off-by: Ryan Foster <[email protected]> --- scripts/checkpatch.pl | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-)
scripts/checkpatch.pl +3 -3
@@ -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) &&
Signature · 1 line
2.52.0
Quoted 5 lines · Joe Perches
Random grep results:
Note: seems to be used as well
What about NB: and INVARIANTS ?
Thanks Joe, it is very appreciated that you review checkpatch patches.
INVARIANTS should have been INVARIANT (or the other way around, but since we mostly use INVARIANT, I guess it is better to stick with it now).
Cheers,
Miguel
Quoted 25 lines · Ryan Foster
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() { }
Quoted 2 lines
Yeah, the suggestion was mostly about detecting docs for private items that used normal comments (//). For public items, the compiler should already be warning on its own, but it doesn't hurt if checkpatch does too, of course.
Did you get a lot of false positives without the logic to exclude "//
SAFETY: " etc.? I suggested that heuristics as a possible idea to remove false positives if it was needed, but perhaps it was fine without?
By the way, to clarify, for this example you give above:
// SAFETY: The `ptr` is guaranteed by the C code to be valid.
unsafe fn foo() { }wouldn't hurt if it triggers either way, because it is actually wrong, i.e. it should be a # Safety section (in this case I guess your lint doesn't trigger because there is no intra-doc link anyway).
Thanks!
Cheers,
Miguel