Fix comment_references to flag keywords (#808).

Update `comment_references` to check for keywords that are not treated as references by the parser
but should be flagged by the linter.

Fixes: #808.

lib/src/rules/comment_references.dart

@@ -3,6 +3,7 @@
 // BSD-style license that can be found in the LICENSE file.
 
 import 'package:analyzer/dart/ast/ast.dart';
+import 'package:analyzer/dart/ast/token.dart';
 import 'package:analyzer/dart/ast/visitor.dart';
 import 'package:linter/src/analyzer.dart';
 
@@ -48,11 +49,43 @@ class Visitor extends SimpleAstVisitor {
   final LintRule rule;
   Visitor(this.rule);
 
+  @override
+  visitComment(Comment node) {
+    // Check for keywords that are not treated as references by the parser
+    // but should be flagged by the linter.
+    // Note that no special care is taken to handle embedded code blocks.
+    for (Token token in node.tokens) {
+      if (!token.isSynthetic) {
+        String comment = token.lexeme;
+        int length = comment.length;
+        int leftIndex = comment.indexOf('[');
+        while (leftIndex >= 0 && leftIndex + 1 < length) {
+          int rightIndex = comment.indexOf(']', leftIndex);
+          if (rightIndex >= 0) {
+            String reference = comment.substring(leftIndex + 1, rightIndex);
+            if (_isParserSpecialCase(reference)) {
+              int nameOffset = token.offset + leftIndex + 1;
+              rule.reporter.reportErrorForOffset(
+                  rule.lintCode, nameOffset, reference.length);
+            }
+          }
+          leftIndex = comment.indexOf('[', rightIndex);
+        }
+      }
+    }
+  }
+
   @override
   visitCommentReference(CommentReference node) {
     Identifier identifier = node.identifier;
     if (!identifier.isSynthetic && identifier.bestElement == null) {
       rule.reportLint(identifier);
     }
   }
+
+  bool _isParserSpecialCase(String reference) =>
+      reference == 'this' ||
+      reference == 'null' ||
+      reference == 'true' ||
+      reference == 'false';
 }

test/rules/comment_references.dart

@@ -4,6 +4,12 @@
 
 // test w/ `pub run test -N comment_references`
 
+/// Keywords special cased by the parser should nonetheless lint:
+/// [this] #LINT
+/// [null] #LINT
+/// [true] #LINT
+/// [false] #LINT
+
 /// Writes [y]. #LINT
 void write(int x) {}