Incremental resolution of updated DartDoc 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 25 matching lines @@
   Token copy() => new BeginToken(type, offset);
 }
 
 /**
  * A `BeginTokenWithComment` is a begin token that is preceded by comments.
  */
 class BeginTokenWithComment extends BeginToken {
   /**
    * The first comment in the list of comments that precede this token.
    */
-  final Token _precedingComment;
+  CommentToken precedingComments;
 
   /**
    * Initialize a newly created token to have the given [type] at the given
    * [offset] and to be preceded by the comments reachable from the given
    * [comment].
    */
-  BeginTokenWithComment(TokenType type, int offset, this._precedingComment)
-      : super(type, offset);
-
-  @override
-  Token get precedingComments => _precedingComment;
+  BeginTokenWithComment(TokenType type, int offset, this.precedingComments)
+      : super(type, offset) {
+    if (precedingComments != null) {
+      precedingComments.parent = this;

[Brian Wilkerson, 2014/12/01 14:21:24]

It seems strange to me that only the first of the preceedingComments would have
its parent field set. I think that will be confusing to other clients.

+    }
+  }
 
   @override
   void applyDelta(int delta) {
     super.applyDelta(delta);
-    Token token = _precedingComment;
+    Token token = precedingComments;
     while (token != null) {
       token.applyDelta(delta);
       token = token.next;
     }
   }
 
   @override
   Token copy() =>
-      new BeginTokenWithComment(type, offset, copyComments(_precedingComment));
+      new BeginTokenWithComment(type, offset, copyComments(precedingComments));
 }
 
 /**
- * A `CharSequenceReader` is a [CharacterReader] that reads characters from a
- * character sequence.
- */
-class CharSequenceReader implements CharacterReader {
-  /**
-   * The sequence from which characters will be read.
-   */
-  final String _sequence;
-
-  /**
-   * The number of characters in the string.
-   */
-  int _stringLength = 0;
-
-  /**
-   * The index, relative to the string, of the last character that was read.
-   */
-  int _charOffset = 0;
-
-  /**
-   * Initialize a newly created reader to read the characters in the given
-   * [_sequence].
-   */
-  CharSequenceReader(this._sequence) {
-    this._stringLength = _sequence.length;
-    this._charOffset = -1;
-  }
-
-  @override
-  int get offset => _charOffset;
-
-  @override
-  void set offset(int offset) {
-    _charOffset = offset;
-  }
-
-  @override
-  int advance() {
-    if (_charOffset + 1 >= _stringLength) {
-      return -1;
-    }
-    return _sequence.codeUnitAt(++_charOffset);
-  }
-
-  @override
-  String getString(int start, int endDelta) =>
-      _sequence.substring(start, _charOffset + 1 + endDelta).toString();
-
-  @override
-  int peek() {
-    if (_charOffset + 1 >= _stringLength) {
-      return -1;
-    }
-    return _sequence.codeUnitAt(_charOffset + 1);
-  }
-}
-
-/**
  * A `CharacterRangeReader` is a [CharacterReader] that reads a range of
  * characters from another character reader.
  */
 class CharacterRangeReader extends CharacterReader {
   /**
    * The reader from which the characters are actually being read.
    */
   final CharacterReader baseReader;
 
   /**
@@ skipping 74 matching lines @@
   String getString(int start, int endDelta);
 
   /**
    * Return the character at the current position without changing the current
    * position.
    */
   int peek();
 }
 
 /**
+ * A `CharSequenceReader` is a [CharacterReader] that reads characters from a
+ * character sequence.
+ */
+class CharSequenceReader implements CharacterReader {
+  /**
+   * The sequence from which characters will be read.
+   */
+  final String _sequence;
+
+  /**
+   * The number of characters in the string.
+   */
+  int _stringLength = 0;
+
+  /**
+   * The index, relative to the string, of the last character that was read.
+   */
+  int _charOffset = 0;
+
+  /**
+   * Initialize a newly created reader to read the characters in the given
+   * [_sequence].
+   */
+  CharSequenceReader(this._sequence) {
+    this._stringLength = _sequence.length;
+    this._charOffset = -1;
+  }
+
+  @override
+  int get offset => _charOffset;
+
+  @override
+  void set offset(int offset) {
+    _charOffset = offset;
+  }
+
+  @override
+  int advance() {
+    if (_charOffset + 1 >= _stringLength) {
+      return -1;
+    }
+    return _sequence.codeUnitAt(++_charOffset);
+  }
+
+  @override
+  String getString(int start, int endDelta) =>
+      _sequence.substring(start, _charOffset + 1 + endDelta).toString();
+
+  @override
+  int peek() {
+    if (_charOffset + 1 >= _stringLength) {
+      return -1;
+    }
+    return _sequence.codeUnitAt(_charOffset + 1);
+  }
+}
+
+/**
+ * A `CommentToken` is a token representing a comment.
+ */
+class CommentToken extends StringToken {
+  /**
+   * The [Token] that contains this comment.
+   */
+  Token parent;
+
+  /**
+   * 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);
+}
+
+/**
  * The enumeration `Keyword` defines the keywords in the Dart programming
  * language.
  */
 class Keyword {
   static const Keyword ASSERT = const Keyword('ASSERT', "assert");
 
   static const Keyword BREAK = const Keyword('BREAK', "break");
 
   static const Keyword CASE = const Keyword('CASE', "case");
 
@@ skipping 330 matching lines @@
   Keyword value() => keyword;
 }
 
 /**
  * A `KeywordTokenWithComment` is a keyword token that is preceded by comments.
  */
 class KeywordTokenWithComment extends KeywordToken {
   /**
    * The first comment in the list of comments that precede this token.
    */
-  final Token _precedingComment;
+  CommentToken precedingComments;
 
   /**
    * Initialize a newly created token to to represent the given [keyword] at the
    * given [offset] and to be preceded by the comments reachable from the given
    * [comment].
    */
-  KeywordTokenWithComment(Keyword keyword, int offset, this._precedingComment)
-      : super(keyword, offset);
-
-  @override
-  Token get precedingComments => _precedingComment;
+  KeywordTokenWithComment(Keyword keyword, int offset, this.precedingComments)
+      : super(keyword, offset) {
+    if (precedingComments != null) {
+      precedingComments.parent = this;
+    }
+  }
 
   @override
   void applyDelta(int delta) {
     super.applyDelta(delta);
-    Token token = _precedingComment;
+    Token token = precedingComments;
     while (token != null) {
       token.applyDelta(delta);
       token = token.next;
     }
   }
 
   @override
   Token copy() =>
-      new KeywordTokenWithComment(keyword, offset, copyComments(_precedingComment));
+      new KeywordTokenWithComment(keyword, offset, copyComments(precedingComments));
 }
 
 /**
  * The class `Scanner` implements a scanner for Dart code.
  *
  * The lexical structure of Dart is ambiguous without knowledge of the context
  * in which a token is being scanned. For example, without context we cannot
  * determine whether source of the form "<<" should be scanned as a single
  * left-shift operator or as two left angle brackets. This scanner does not have
  * any context, so it always resolves such conflicts by scanning the longest
@@ skipping 338 matching lines @@
     _stackEnd++;
   }
 
   void _appendCommentToken(TokenType type, String value) {
     // Ignore comment tokens if client specified that it doesn't need them.
     if (!_preserveComments) {
       return;
     }
     // OK, remember comment tokens.
     if (_firstComment == null) {
-      _firstComment = new StringToken(type, value, _tokenStart);
+      _firstComment = new CommentToken(type, value, _tokenStart);
       _lastComment = _firstComment;
     } else {
       _lastComment =
-          _lastComment.setNext(new StringToken(type, value, _tokenStart));
+          _lastComment.setNext(new CommentToken(type, value, _tokenStart));
     }
   }
 
   void _appendEndToken(TokenType type, TokenType beginType) {
     Token token;
     if (_firstComment == null) {
       token = new Token(type, _tokenStart);
     } else {
       token = new TokenWithComment(type, _tokenStart, _firstComment);
       _firstComment = null;
@@ skipping 837 matching lines @@
   String value() => _value;
 }
 
 /**
  * A `StringTokenWithComment` is a string token that is preceded by comments.
  */
 class StringTokenWithComment extends StringToken {
   /**
    * The first comment in the list of comments that precede this token.
    */
-  final Token _precedingComment;
+  CommentToken precedingComments;
 
   /**
    * Initialize a newly created token to have the given [type] at the given
    * [offset] and to be preceded by the comments reachable from the given
    * [comment].
    */
   StringTokenWithComment(TokenType type, String value, int offset,
-      this._precedingComment)
-      : super(type, value, offset);
-
-  @override
-  Token get precedingComments => _precedingComment;
+      this.precedingComments)
+      : super(type, value, offset) {
+    if (precedingComments != null) {
+      precedingComments.parent = this;
+    }
+  }
 
   @override
   void applyDelta(int delta) {
     super.applyDelta(delta);
-    Token token = _precedingComment;
+    Token token = precedingComments;
     while (token != null) {
       token.applyDelta(delta);
       token = token.next;
     }
   }
 
   @override
   Token copy() =>
       new StringTokenWithComment(
           type,
           lexeme,
           offset,
-          copyComments(_precedingComment));
+          copyComments(precedingComments));
 }
 
 /**
  * A `SubSequenceReader` is a [CharacterReader] that reads characters from a
  * character sequence, but adds a delta when reporting the current character
  * offset so that the character sequence can be a subsequence from a larger
  * sequence.
  */
 class SubSequenceReader extends CharSequenceReader {
   /**
@@ skipping 110 matching lines @@
    */
   Token get next => _next;
 
   /**
    * 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 precceding comment token will have a lexeme of "/* one */" and
+   * 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;
 
   /**
    * Apply (add) the given [delta] to this token's offset.
    */
   void applyDelta(int delta) {
     offset += delta;
   }
@@ skipping 547 matching lines @@
   String toString() => "-eof-";
 }
 
 /**
  * A `TokenWithComment` is a normal token that is preceded by comments.
  */
 class TokenWithComment extends Token {
   /**
    * The first comment in the list of comments that precede this token.
    */
-  final Token _precedingComment;
+  CommentToken precedingComments;
 
   /**
    * Initialize a newly created token to have the given [type] at the given
    * [offset] and to be preceded by the comments reachable from the given
    * [comment].
    */
-  TokenWithComment(TokenType type, int offset, this._precedingComment)
-      : super(type, offset);
+  TokenWithComment(TokenType type, int offset, this.precedingComments)
+      : super(type, offset) {
+    if (precedingComments != null) {
+      precedingComments.parent = this;
+    }
+  }
 
   @override
-  Token get precedingComments => _precedingComment;
-
-  @override
-  Token copy() => new TokenWithComment(type, offset, _precedingComment);
+  Token copy() => new TokenWithComment(type, offset, precedingComments);
 }