initial generic method comment parsing

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';
@@ skipping 228 matching lines @@
    * 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);
 }
 
+class GenericMethodCommentToken extends CommentToken {

[Brian Wilkerson, 2015/11/11 21:53:42]

It isn't clear to me that we need a separate class. DocumentationCommentToken
exists as a separate class because it has an additional field. Instead of 'is'
tests (which are expensive) we could test the token type of the comment tokens.

[Jennifer Messerly, 2015/11/12 00:20:00]

Good catch. Yeah I think my order was I made the class, then realized I wanted
two distinct types ... then realized checking the .type was faster anyway ...
but forgot to go back and clean up the class. Removed!

+  /**
+   * Initialize a newly created token to represent a token of the given [type]
+   * with the given [value] at the given [offset].
+   */
+  GenericMethodCommentToken(TokenType type, String value, int offset)
+      : super(type, value, offset);
+
+  @override
+  GenericMethodCommentToken copy() =>
+      new GenericMethodCommentToken(type, _value, offset);
+}
+
 /**
  * A documentation comment token.
  */
 class DocumentationCommentToken extends CommentToken {
   /**
    * 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>[];
@@ skipping 457 matching lines @@
    * empty.
    */
   int _stackEnd = -1;
 
   /**
    * A flag indicating whether any unmatched groups were found during the parse.
    */
   bool _hasUnmatchedGroups = false;
 
   /**
+   * A flag indicating whether to parse generic method comments, of the form

[Brian Wilkerson, 2015/11/11 21:53:42]

Maybe "parse" --> "scan" in both the comment and the name?

[Jennifer Messerly, 2015/11/12 00:20:00]

Sounds good to me. Done.

+   * `/*=T*/` and `/*<T>*/`.
+   */
+  bool parseGenericMethodComments = false;
+
+  /**
    * Initialize a newly created scanner to scan characters from the given
    * [source]. The given character [_reader] will be used to read the characters
    * in the source. The given [_errorListener] will be informed of any errors
    * that are found.
    */
   Scanner(this.source, this._reader, this._errorListener) {
     _tokens = new Token(TokenType.EOF, -1);
     _tokens.setNext(_tokens);
     _tail = _tokens;
     _tokenStart = -1;
@@ skipping 269 matching lines @@
       token = new BeginTokenWithComment(type, _tokenStart, _firstComment);
       _firstComment = null;
       _lastComment = null;
     }
     _tail = _tail.setNext(token);
     _groupingStack.add(token);
     _stackEnd++;
   }
 
   void _appendCommentToken(TokenType type, String value) {
-    // Ignore comment tokens if client specified that it doesn't need them.
-    if (!_preserveComments) {
+    CommentToken token = null;
+    TokenType genericComment = _matchGenericMethodCommentType(value);
+    if (genericComment != null) {
+      token = new GenericMethodCommentToken(genericComment, value, _tokenStart);
+    } else if (!_preserveComments) {
+      // Ignore comment tokens if client specified that it doesn't need them.
       return;
-    }
-    // OK, remember comment tokens.
-    CommentToken token;
-    if (_isDocumentationComment(value)) {
-      token = new DocumentationCommentToken(type, value, _tokenStart);
     } else {
-      token = new CommentToken(type, value, _tokenStart);
+      // OK, remember comment tokens.
+      if (_isDocumentationComment(value)) {
+        token = new DocumentationCommentToken(type, value, _tokenStart);
+      } else {
+        token = new CommentToken(type, value, _tokenStart);
+      }
     }
     if (_firstComment == null) {
       _firstComment = token;
       _lastComment = _firstComment;
     } else {
       _lastComment = _lastComment.setNext(token);
     }
   }
 
   void _appendEndToken(TokenType type, TokenType beginType) {
@@ skipping 778 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);
   }
+
+  /**
+   * Checks if [value] is the start of a generic method type annotation comment.
+   *
+   * This can either be of the form `/*<T>*/` or `/*=T*/`. The token type is
+   * returned, or null if it was not a generic method comment.
+   */
+  TokenType _matchGenericMethodCommentType(String value) {
+    if (parseGenericMethodComments) {
+      // Match /*< and >*/
+      if (StringUtilities.startsWith3(value, 0, 0x2F, 0x2A, 0x3C) &&
+          StringUtilities.endsWith3(value, 0x3E, 0x2A, 0x2F)) {
+        return TokenType.GENERIC_METHOD_TYPE_LIST;
+      }
+      // Match /*=
+      if (StringUtilities.startsWith3(value, 0, 0x2F, 0x2A, 0x3D)) {
+        return TokenType.GENERIC_METHOD_TYPE_ASSIGN;
+      }
+    }
+    return null;
+  }
 }
 
 /**
  * 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 =
@@ skipping 217 matching lines @@
    * Return the next token in the token stream.
    */
   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 preceding comment token will have a lexeme of "/* one */" and
-   * the next comment token will have a lexeme of "/* two */".
+   * 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 */`.
    */
   CommentToken get precedingComments => null;
 
   /**
    * Apply (add) the given [delta] to this token's offset.
    */
   void applyDelta(int delta) {
     offset += delta;
   }
 
@@ skipping 421 matching lines @@
 
   static const TokenType BACKPING =
       const TokenType('BACKPING', TokenClass.NO_CLASS, "`");
 
   static const TokenType BACKSLASH =
       const TokenType('BACKSLASH', TokenClass.NO_CLASS, "\\");
 
   static const TokenType PERIOD_PERIOD_PERIOD =
       const TokenType('PERIOD_PERIOD_PERIOD', TokenClass.NO_CLASS, "...");
 
+  static const TokenType GENERIC_METHOD_TYPE_LIST =
+      const TokenType('GENERIC_METHOD_TYPE_LIST');
+
+  static const TokenType GENERIC_METHOD_TYPE_ASSIGN =
+      const TokenType('GENERIC_METHOD_TYPE_ASSIGN');
+
   /**
    * The class of the token.
    */
   final TokenClass _tokenClass;
 
   /**
    * The name of the token type.
    */
   final String name;
 
@@ skipping 148 matching lines @@
   CommentToken get precedingComments => _precedingComment;
 
   void set precedingComments(CommentToken comment) {
     _precedingComment = comment;
     _setCommentParent(_precedingComment);
   }
 
   @override
   Token copy() => new TokenWithComment(type, offset, precedingComments);
 }