[v1] checkpatch: warn on Rust comments with rustdoc links above items

[PATCH] checkpatch: warn on Rust comments with rustdoc links above items

Posted by Ryan Foster 3 weeks, 4 days ago

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@kernel.org>
Signed-off-by: Ryan Foster <foster.ryan.r@gmail.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

Re: [PATCH] checkpatch: warn on Rust comments with rustdoc links above items

Posted by Miguel Ojeda 3 weeks, 4 days ago

On Tue, Jan 13, 2026 at 9:21 PM Ryan Foster <foster.ryan.r@gmail.com> wrote:
>
> 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@kernel.org>

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

Re: [PATCH] checkpatch: warn on Rust comments with rustdoc links above items

Posted by Joe Perches 3 weeks, 4 days ago

On Tue, 2026-01-13 at 12:21 -0800, Ryan Foster wrote:
> 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.
[]
> diff --git 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+(.*)$/) {

No objection but maybe $rawline should be something like:

		    $rawline =~ m{^\+\s*//(?![/!])(.*)} {
			my $comment_text = $1;

etc...

> +			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);

[]

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:

Re: [PATCH] checkpatch: warn on Rust comments with rustdoc links above items

Posted by Miguel Ojeda 3 weeks, 4 days ago

On Tue, Jan 13, 2026 at 9:57 PM Joe Perches <joe@perches.com> wrote:
>
> 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

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

Posted by Ryan Foster 3 weeks, 4 days ago

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@kernel.org>
Suggested-by: Joe Perches <joe@perches.com>
Signed-off-by: Ryan Foster <foster.ryan.r@gmail.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

Re: [PATCH v2] checkpatch: warn on Rust comments with rustdoc links above items

Posted by Joe Perches 3 weeks, 4 days ago

On Tue, 2026-01-13 at 13:10 -0800, Ryan Foster wrote:
> 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

Posted by Ryan Foster 3 weeks, 4 days ago

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@kernel.org>
Signed-off-by: Ryan Foster <foster.ryan.r@gmail.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@gmail.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@kernel.org>
Suggested-by: Joe Perches <joe@perches.com>
Signed-off-by: Ryan Foster <foster.ryan.r@gmail.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