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

[Joe Perches <joe@perches.com>]

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: