Another pass over scanner 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 'java_engine.dart';
 import 'source.dart';
 
 /**
- * A `BeginToken` is the opening half of a grouping pair of tokens. This is used
- * for curly brackets ('{'), parentheses ('('), and square brackets ('[').
+ * The opening half of a grouping pair of tokens. This is used for curly
+ * brackets ('{'), parentheses ('('), and square brackets ('[').
  */
 class BeginToken extends Token {
   /**
    * The token that corresponds to this token.
    */
   Token endToken;
 
   /**
    * Initialize a newly created token to have the given [type] at the given
    * [offset].
    */
   BeginToken(TokenType type, int offset) : super(type, offset) {
     assert(type == TokenType.OPEN_CURLY_BRACKET ||
         type == TokenType.OPEN_PAREN ||
         type == TokenType.OPEN_SQUARE_BRACKET ||
         type == TokenType.STRING_INTERPOLATION_EXPRESSION);
   }
 
   @override
   Token copy() => new BeginToken(type, offset);
 }
 
 /**
- * A `BeginTokenWithComment` is a begin token that is preceded by comments.
+ * A begin token that is preceded by comments.
  */
 class BeginTokenWithComment extends BeginToken {
   /**
    * The first comment in the list of comments that precede this token.
    */
   CommentToken _precedingComment;
 
   /**
    * 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
@@ skipping 20 matching lines @@
       token = token.next;
     }
   }
 
   @override
   Token copy() =>
       new BeginTokenWithComment(type, offset, copyComments(precedingComments));
 }
 
 /**
- * A `CharacterRangeReader` is a [CharacterReader] that reads a range of
- * characters from another character reader.
+ * 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;
 
   /**
    * The last character to be read.
    */
@@ skipping 30 matching lines @@
   @override
   int peek() {
     if (baseReader.offset + 1 >= endIndex) {
       return -1;
     }
     return baseReader.peek();
   }
 }
 
 /**
- * A `CharacterReader` is used by the scanner to read the characters to be
- * scanned.
+ * An object used by the scanner to read the characters to be scanned.
  */
 abstract class CharacterReader {
   /**
    * The current offset relative to the beginning of the source. Return the
    * initial offset if the scanner has not yet scanned the source code, and one
    * (1) past the end of the source code if the entire source code has been
    * scanned.
    */
   int get offset;
 
@@ skipping 20 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.
+ * 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.
    */
@@ skipping 36 matching lines @@
   @override
   int peek() {
     if (_charOffset + 1 >= _stringLength) {
       return -1;
     }
     return _sequence.codeUnitAt(_charOffset + 1);
   }
 }
 
 /**
- * A `CommentToken` is a token representing a comment.
+ * 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].
@@ skipping 21 matching lines @@
    * with the given [value] at the given [offset].
    */
   DocumentationCommentToken(TokenType type, String value, int offset)
       : super(type, value, offset);
 
   @override
   CommentToken copy() => new DocumentationCommentToken(type, _value, offset);
 }
 
 /**
- * The enumeration `Keyword` defines the keywords in the Dart programming
- * language.
+ * 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");
 
   static const Keyword CATCH = const Keyword('CATCH', "catch");
 
@@ skipping 178 matching lines @@
     LinkedHashMap<String, Keyword> result =
         new LinkedHashMap<String, Keyword>();
     for (Keyword keyword in values) {
       result[keyword.syntax] = keyword;
     }
     return result;
   }
 }
 
 /**
- * A `KeywordState` is a state in a state machine used to scan keywords.
+ * A state in a state machine used to scan keywords.
  */
 class KeywordState {
   /**
    * An empty transition table used by leaf states.
    */
   static List<KeywordState> _EMPTY_TABLE = new List<KeywordState>(26);
 
   /**
    * The initial state in the state machine.
    */
@@ skipping 31 matching lines @@
    * [character], or `null` if there is no valid state reachable from this state
    * with such a transition.
    */
   KeywordState next(int character) => _table[character - 0x61];
 
   /**
    * Create the next state in the state machine where we have already recognized
    * the subset of strings in the given array of [strings] starting at the given
    * [offset] and having the given [length]. All of these strings have a common
    * prefix and the next character is at the given [start] index.
-   *
-   * [start] the index of the character in the strings used to transition to a
-   * new state
-   * [strings] an array containing all of the strings that will be recognized by
-   * the state machine
-   * [offset] the offset of the first string in the array that has the prefix
-   * that is assumed to have been recognized by the time we reach the state
-   * being built
-   * [length] the number of strings in the array that pass through the state
-   * being built
    */
   static KeywordState _computeKeywordStateTable(
       int start, List<String> strings, int offset, int length) {
     List<KeywordState> result = new List<KeywordState>(26);
     assert(length != 0);
     int chunk = 0x0;
     int chunkStart = -1;
     bool isLeaf = false;
     for (int i = offset; i < offset + length; i++) {
       if (strings[i].length == start) {
@@ skipping 34 matching lines @@
     List<String> strings = new List<String>(values.length);
     for (int i = 0; i < values.length; i++) {
       strings[i] = values[i].syntax;
     }
     strings.sort();
     return _computeKeywordStateTable(0, strings, 0, strings.length);
   }
 }
 
 /**
- * A `KeywordToken` is a keyword in the language.
+ * A token representing a keyword in the language.
  */
 class KeywordToken extends Token {
   /**
    * The keyword being represented by this token.
    */
   final Keyword keyword;
 
   /**
    * Initialize a newly created token to represent the given [keyword] at the
    * given [offset].
    */
   KeywordToken(this.keyword, int offset) : super(TokenType.KEYWORD, offset);
 
   @override
   String get lexeme => keyword.syntax;
 
   @override
   Token copy() => new KeywordToken(keyword, offset);
 
   @override
   Keyword value() => keyword;
 }
 
 /**
- * A `KeywordTokenWithComment` is a keyword token that is preceded by comments.
+ * A keyword token that is preceded by comments.
  */
 class KeywordTokenWithComment extends KeywordToken {
   /**
    * The first comment in the list of comments that precede this token.
    */
   CommentToken _precedingComment;
 
   /**
    * 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
@@ skipping 306 matching lines @@
 
   /**
    * Record the fact that we are at the beginning of a new line in the source.
    */
   void recordStartOfLine() {
     _lineStarts.add(_reader.offset);
   }
 
   /**
    * Record that the source begins on the given [line] and [column] at the
-   * current offset as given by the reader. The line starts for lines before the
-   * given line will not be correct.
+   * current offset as given by the reader. Both the line and the column are
+   * one-based indexes. The line starts for lines before the given line will not
+   * be correct.
    *
    * This method must be invoked at most one time and must be invoked before
    * scanning begins. The values provided must be sensible. The results are
    * undefined if these conditions are violated.
-   *
-   * [line] the one-based index of the line containing the first character of
-   * the source
-   * [column] the one-based index of the column in which the first character of
-   * the source occurs
    */
   void setSourceStart(int line, int column) {
     int offset = _reader.offset;
     if (line < 1 || column < 1 || offset < 0 || (line + column - 2) >= offset) {
       return;
     }
     for (int i = 2; i < line; i++) {
       _lineStarts.add(1);
     }
     _lineStarts.add(offset - column + 1);
@@ skipping 160 matching lines @@
     }
     //
     // We should never get to this point because we wouldn't be inside a string
     // interpolation expression unless we had previously found the start of the
     // expression.
     //
     return null;
   }
 
   /**
-   * Report an error at the current offset.
-   *
-   * [errorCode] the error code indicating the nature of the error
-   * [arguments] any arguments needed to complete the error message
+   * Report an error at the current offset. The [errorCode] is the error code
+   * indicating the nature of the error. The [arguments] are any arguments
+   * needed to complete the error message
    */
   void _reportError(ScannerErrorCode errorCode, [List<Object> arguments]) {
     _errorListener.onError(new AnalysisError.con2(
         source, _reader.offset, 1, errorCode, arguments));
   }
 
   int _select(int choice, TokenType yesType, TokenType noType) {
     int next = _reader.advance();
     if (next == choice) {
       _appendTokenOfType(yesType);
@@ skipping 623 matching lines @@
   /**
    * Checks if [value] is a single-line or multi-line comment.
    */
   static bool _isDocumentationComment(String value) {
     return StringUtilities.startsWith3(value, 0, 0x2F, 0x2F, 0x2F) ||
         StringUtilities.startsWith3(value, 0, 0x2F, 0x2A, 0x2A);
   }
 }
 
 /**
- * The enumeration `ScannerErrorCode` defines the error codes used for errors
- * detected by the scanner.
+ * The error codes used for errors detected by the scanner.
  */
 class ScannerErrorCode extends ErrorCode {
   static const ScannerErrorCode ILLEGAL_CHARACTER =
       const ScannerErrorCode('ILLEGAL_CHARACTER', "Illegal character {0}");
 
   static const ScannerErrorCode MISSING_DIGIT =
       const ScannerErrorCode('MISSING_DIGIT', "Decimal digit expected");
 
   static const ScannerErrorCode MISSING_HEX_DIGIT =
       const ScannerErrorCode('MISSING_HEX_DIGIT', "Hexidecimal digit expected");
@@ skipping 22 matching lines @@
       : super(name, message, correction);
 
   @override
   ErrorSeverity get errorSeverity => ErrorSeverity.ERROR;
 
   @override
   ErrorType get type => ErrorType.SYNTACTIC_ERROR;
 }
 
 /**
- * A `StringToken` is a token whose value is independent of it's type.
+ * A token whose value is independent of it's type.
  */
 class StringToken extends Token {
   /**
    * The lexeme represented by this token.
    */
   String _value;
 
   /**
    * Initialize a newly created token to represent a token of the given [type]
    * with the given [value] at the given [offset].
    */
   StringToken(TokenType type, String value, int offset) : super(type, offset) {
     this._value = StringUtilities.intern(value);
   }
 
   @override
   String get lexeme => _value;
 
   @override
   Token copy() => new StringToken(type, _value, offset);
 
   @override
   String value() => _value;
 }
 
 /**
- * A `StringTokenWithComment` is a string token that is preceded by comments.
+ * A string token that is preceded by comments.
  */
 class StringTokenWithComment extends StringToken {
   /**
    * The first comment in the list of comments that precede this token.
    */
   CommentToken _precedingComment;
 
   /**
    * 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
@@ skipping 21 matching lines @@
       token = token.next;
     }
   }
 
   @override
   Token copy() => new StringTokenWithComment(
       type, lexeme, offset, 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.
+ * 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 {
   /**
    * The offset from the beginning of the file to the beginning of the source
    * being scanned.
    */
   final int _offsetDelta;
 
   /**
    * Initialize a newly created reader to read the characters in the given
    * [sequence]. The [_offsetDelta] is the offset from the beginning of the file
    * to the beginning of the source being scanned
    */
   SubSequenceReader(String sequence, this._offsetDelta) : super(sequence);
 
   @override
   int get offset => _offsetDelta + super.offset;
 
   @override
   void set offset(int offset) {
     super.offset = offset - _offsetDelta;
   }
 
   @override
   String getString(int start, int endDelta) =>
       super.getString(start - _offsetDelta, endDelta);
 }
 
 /**
- * A `SyntheticStringToken` is a token whose value is independent of it's type.
+ * A token whose value is independent of it's type.
  */
 class SyntheticStringToken extends StringToken {
   /**
    * Initialize a newly created token to represent a token of the given [type]
    * with the given [value] at the given [offset].
    */
   SyntheticStringToken(TokenType type, String value, int offset)
       : super(type, value, offset);
 
   @override
   bool get isSynthetic => true;
 }
 
 /**
- * Instances of the class `Token` represent a token that was scanned from the
- * input. Each token knows which tokens preceed and follow it, acting as a link
- * in a doubly linked list of tokens.
+ * A token that was scanned from the input. Each token knows which tokens
+ * precede and follow it, acting as a link in a doubly linked list of tokens.
  */
 class Token {
   /**
    * The type of the token.
    */
   final TokenType type;
 
   /**
    * The offset from the beginning of the file to the first character in the
    * token.
@@ skipping 166 matching lines @@
       if (token != null && (offset < 0 || token.offset < offset)) {
         first = token;
         offset = token.offset;
       }
     }
     return first;
   }
 }
 
 /**
- * The enumeration `TokenClass` represents classes (or groups) of tokens with a
- * similar use.
+ * The classes (or groups) of tokens with a similar use.
  */
 class TokenClass {
   /**
    * A value used to indicate that the token type is not part of any specific
    * class of token.
    */
   static const TokenClass NO_CLASS = const TokenClass('NO_CLASS');
 
   /**
    * A value used to indicate that the token type is an additive operator.
@@ skipping 96 matching lines @@
    */
   final int precedence;
 
   const TokenClass(this.name, [this.precedence = 0]);
 
   @override
   String toString() => name;
 }
 
 /**
- * The enumeration `TokenType` defines the types of tokens that can be returned
- * by the scanner.
+ * The types of tokens that can be returned by the scanner.
  */
 class TokenType {
   /**
    * The type of the token that marks the end of the input.
    */
   static const TokenType EOF = const TokenType_EOF('EOF');
 
   static const TokenType DOUBLE = const TokenType('DOUBLE');
 
   static const TokenType HEXADECIMAL = const TokenType('HEXADECIMAL');
@@ skipping 320 matching lines @@
 }
 
 class TokenType_EOF extends TokenType {
   const TokenType_EOF(String name) : super(name, TokenClass.NO_CLASS, "");
 
   @override
   String toString() => "-eof-";
 }
 
 /**
- * A `TokenWithComment` is a normal token that is preceded by comments.
+ * A normal token that is preceded by comments.
  */
 class TokenWithComment extends Token {
   /**
    * The first comment in the list of comments that precede this token.
    */
   CommentToken _precedingComment;
 
   /**
    * 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) {
     _setCommentParent(_precedingComment);
   }
 
   CommentToken get precedingComments => _precedingComment;
 
   void set precedingComments(CommentToken comment) {
     _precedingComment = comment;
     _setCommentParent(_precedingComment);
   }
 
   @override
   Token copy() => new TokenWithComment(type, offset, precedingComments);
 }