Updated detached tokens of references in documentation comments.

pkg/analyzer/lib/src/generated/scanner.dart

 // Copyright (c) 2014, 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 engine.scanner;
 
 import 'dart:collection';
 
 import 'error.dart';
 import 'instrumentation.dart';
@@ skipping 221 matching lines @@
 /**
  * A `CommentToken` is a token representing a comment.
  */
 class CommentToken extends StringToken {
   /**
    * The [Token] that contains this comment.
    */
   Token parent;
 
   /**
+   * The references embedded within the documentation comment.
+   * This list will be empty unless this is a documentation comment that has
+   * references embedded within it.
+   */
+  final List<Token> references = <Token>[];

[Brian Wilkerson, 2014/12/01 19:41:19]

How hard would it be to have a subclass of CommentToken named something like
DocumentationCommentToken that had a actual field for 'references' and a getter
in CommentToken that returned an unmodifiable empty list of tokens? It would be
nice to not have the extra objects taking up space when we don't need them.

[scheglov, 2014/12/01 22:49:22]

https://codereview.chromium.org/768233002

+
+  /**
    * Initialize a newly created token to represent a token of the given [type]
    * with the given [value] at the given [offset].
    */
   CommentToken(TokenType type, String value, int offset)
       : super(type, value, offset);
 
   @override
   CommentToken copy() => new CommentToken(type, _value, offset);
 }
 
@@ skipping 1763 matching lines @@
   /**
    * Return the first comment in the list of comments that precede this token,
    * or `null` if there are no comments preceding this token. Additional
    * comments can be reached by following the token stream using [next] until
    * `null` is returned.
    *
    * For example, if the original contents were "/* one */ /* two */ id", then
    * the first preceding comment token will have a lexeme of "/* one */" and
    * the next comment token will have a lexeme of "/* two */".
    */
-  Token get precedingComments => null;
+  CommentToken get precedingComments => null;
 
   /**
    * Apply (add) the given [delta] to this token's offset.
    */
   void applyDelta(int delta) {
     offset += delta;
   }
 
   /**
    * Return a newly created token that is a copy of this token but that is not a
@@ skipping 577 matching lines @@
   CommentToken get precedingComments => _precedingComment;
 
   void set precedingComments(CommentToken comment) {
     _precedingComment = comment;
     _setCommentParent(_precedingComment);
   }
 
   @override
   Token copy() => new TokenWithComment(type, offset, precedingComments);
 }