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

[Ryan Foster <foster.ryan.r@gmail.com>]

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