Lint to detect dangling identifiers in docs (#240).

lib/src/rules/comment_references.dart

+// Copyright (c) 2016, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+library linter.src.rules.comment_references;
+
+import 'package:analyzer/dart/ast/ast.dart';
+import 'package:analyzer/dart/ast/visitor.dart';
+import 'package:linter/src/linter.dart';
+
+const desc = r'Only reference in-scope identifers in doc comments.';
+
+const details = r'''
+**DO** reference only in-scope identifers in doc comments.
+
+If you surround things like variable, method, or type names in square brackets,
+then [dartdoc](https://www.dartlang.org/effective-dart/documentation/) will look
+up the name and link to its docs.  For this all to work, ensure that all
+identifiers in docs wrapped in brackets are in-scope.

[Brian Wilkerson, 2016/05/13 14:37:17]

nit: 'in-scope' --> 'in scope'

[pquitslund, 2016/05/13 21:13:16]

Done.

+
+For example,
+
+**GOOD:**
+```
+/// Return the larger of [a] or [b].
+int max_int(int a, int b) { ... }
+```
+
+On the other hand, assuming `outOfScopeId` is out of scope:
+
+**BAD:**
+```
+void f(int outOfScopeId) { ... }

[scheglov, 2016/05/12 21:08:46]

Should there be a documentation comment that references something not existing?

[pquitslund, 2016/05/13 21:13:15]

Acknowledged.

+```
+''';
+
+class CommentReferences extends LintRule {
+  CommentReferences()
+      : super(
+            name: 'comment_references',
+            description: desc,
+            details: details,
+            group: Group.errors);
+
+  @override
+  AstVisitor getVisitor() => new Visitor(this);
+}
+
+class Visitor extends SimpleAstVisitor {
+  final LintRule rule;
+  Visitor(this.rule);
+
+  @override
+  visitCommentReference(CommentReference node) {
+    Identifier identifier = node.identifier;
+    if (!identifier.isSynthetic && identifier.bestElement == null) {
+      rule.reportLint(identifier);
+    }
+  }
+}