Emit a hint when using generic method comment syntax (issue 30356)

pkg/analyzer/lib/src/generated/parser.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 analyzer.parser;
 
 import 'dart:collection';
 import "dart:math" as math;
 
 import 'package:analyzer/dart/ast/ast.dart';
@@ skipping 5174 matching lines @@
     } else {
       type = parseTypeWithoutFunction(inExpression);
     }
     while (_atGenericFunctionTypeAfterReturnType(_currentToken)) {
       type = parseGenericFunctionTypeAfterReturnType(type);
     }
     return type;
   }
 
   /**
-   * Parse a type which is not `void`.
-   *
-   *     typeNotVoid ::=
-   *         functionType
-   *       | typeNotVoidWithoutFunction
-   */
-  TypeAnnotation parseTypeNotVoid(bool inExpression) {
-    TypeAnnotation type = null;
-    if (_atGenericFunctionTypeAfterReturnType(_currentToken)) {
-      // Generic function type with no return type.
-      type = parseGenericFunctionTypeAfterReturnType(null);
-    } else if (_currentToken.keyword == Keyword.VOID &&
-        _atGenericFunctionTypeAfterReturnType(_currentToken.next)) {
-      type = astFactory.typeName(
-          astFactory.simpleIdentifier(getAndAdvance()), null);
-    } else {
-      type = parseTypeName(inExpression);
-    }
-    while (_atGenericFunctionTypeAfterReturnType(_currentToken)) {
-      type = parseGenericFunctionTypeAfterReturnType(type);
-    }
-    return type;
-  }
-
-  /**
-   * Parse a type which is not a function type.
-   *
-   *     typeWithoutFunction ::=
-   *         `void`
-   *       | typeNotVoidWithoutFunction
-   */
-  TypeAnnotation parseTypeWithoutFunction(bool inExpression) {
-    if (_currentToken.keyword == Keyword.VOID) {
-      return astFactory.typeName(
-          astFactory.simpleIdentifier(getAndAdvance()), null);
-    } else {
-      return parseTypeName(inExpression);
-    }
-  }
-
-  /**
    * Parse a list of type arguments. Return the type argument list that was
    * parsed.
    *
    * This method assumes that the current token matches `TokenType.LT`.
    *
    *     typeArguments ::=
    *         '<' typeList '>'
    *
    *     typeList ::=
    *         type (',' type)*
@@ skipping 23 matching lines @@
     TypeName realType = _parseTypeName(inExpression);
     // If this is followed by a generic method type comment, allow the comment
     // type to replace the real type name.
     // TODO(jmesserly): this feels like a big hammer. Can we restrict it to
     // only work inside generic methods?
     TypeName typeFromComment = _parseOptionalTypeNameComment();
     return typeFromComment ?? realType;
   }
 
   /**
+   * Parse a type which is not `void`.
+   *
+   *     typeNotVoid ::=
+   *         functionType
+   *       | typeNotVoidWithoutFunction
+   */
+  TypeAnnotation parseTypeNotVoid(bool inExpression) {
+    TypeAnnotation type = null;
+    if (_atGenericFunctionTypeAfterReturnType(_currentToken)) {
+      // Generic function type with no return type.
+      type = parseGenericFunctionTypeAfterReturnType(null);
+    } else if (_currentToken.keyword == Keyword.VOID &&
+        _atGenericFunctionTypeAfterReturnType(_currentToken.next)) {
+      type = astFactory.typeName(
+          astFactory.simpleIdentifier(getAndAdvance()), null);
+    } else {
+      type = parseTypeName(inExpression);
+    }
+    while (_atGenericFunctionTypeAfterReturnType(_currentToken)) {
+      type = parseGenericFunctionTypeAfterReturnType(type);
+    }
+    return type;
+  }
+
+  /**
    * Parse a type parameter. Return the type parameter that was parsed.
    *
    *     typeParameter ::=
    *         metadata name ('extends' bound)?
    */
   TypeParameter parseTypeParameter() {
     CommentAndMetadata commentAndMetadata = parseCommentAndMetadata();
     SimpleIdentifier name = parseSimpleIdentifier(isDeclaration: true);
     if (_matches(TokenType.QUESTION)) {
       _reportErrorForCurrentToken(ParserErrorCode.NULLABLE_TYPE_PARAMETER);
@@ skipping 23 matching lines @@
     List<TypeParameter> typeParameters = <TypeParameter>[parseTypeParameter()];
     while (_optional(TokenType.COMMA)) {
       typeParameters.add(parseTypeParameter());
     }
     Token rightBracket = _expectGt();
     return astFactory.typeParameterList(
         leftBracket, typeParameters, rightBracket);
   }
 
   /**
+   * Parse a type which is not a function type.
+   *
+   *     typeWithoutFunction ::=
+   *         `void`
+   *       | typeNotVoidWithoutFunction
+   */
+  TypeAnnotation parseTypeWithoutFunction(bool inExpression) {
+    if (_currentToken.keyword == Keyword.VOID) {
+      return astFactory.typeName(
+          astFactory.simpleIdentifier(getAndAdvance()), null);
+    } else {
+      return parseTypeName(inExpression);
+    }
+  }
+
+  /**
    * Parse a unary expression. Return the unary expression that was parsed.
    *
    *     unaryExpression ::=
    *         prefixOperator unaryExpression
    *       | awaitExpression
    *       | postfixExpression
    *       | unaryOperator 'super'
    *       | '-' 'super'
    *       | incrementOperator assignableExpression
    */
@@ skipping 351 matching lines @@
     } else {
       next = skipTypeWithoutFunction(startToken);
     }
     while (next != null && _atGenericFunctionTypeAfterReturnType(next)) {
       next = skipGenericFunctionTypeAfterReturnType(next);
     }
     return next;
   }
 
   /**
-   * Parse a typeWithoutFunction, starting at the [startToken], without actually
-   * creating a TypeAnnotation or changing the current token. Return the token
-   * following the typeWithoutFunction that was parsed, or `null` if the given
-   * token is not the first token in a valid typeWithoutFunction.
-   *
-   * This method must be kept in sync with [parseTypeWithoutFunction].
-   */
-  Token skipTypeWithoutFunction(Token startToken) {
-    if (startToken.keyword == Keyword.VOID) {
-      return startToken.next;
-    } else {
-      return skipTypeName(startToken);
-    }
-  }
-
-  /**
    * Parse a list of type arguments, starting at the [startToken], without
    * actually creating a type argument list or changing the current token.
    * Return the token following the type argument list that was parsed, or
    * `null` if the given token is not the first token in a valid type argument
    * list.
    *
    * This method must be kept in sync with [parseTypeArgumentList].
    *
    *     typeArguments ::=
    *         '<' typeList '>'
@@ skipping 79 matching lines @@
           return next.next;
         }
       }
       previous = next;
       next = next.next;
     }
     return null;
   }
 
   /**
+   * Parse a typeWithoutFunction, starting at the [startToken], without actually
+   * creating a TypeAnnotation or changing the current token. Return the token
+   * following the typeWithoutFunction that was parsed, or `null` if the given
+   * token is not the first token in a valid typeWithoutFunction.
+   *
+   * This method must be kept in sync with [parseTypeWithoutFunction].
+   */
+  Token skipTypeWithoutFunction(Token startToken) {
+    if (startToken.keyword == Keyword.VOID) {
+      return startToken.next;
+    } else {
+      return skipTypeName(startToken);
+    }
+  }
+
+  /**
    * Advance to the next token in the token stream.
    */
   void _advance() {
     _currentToken = _currentToken.next;
   }
 
   /**
    * Append the character equivalent of the given [codePoint] to the given
    * [builder]. Use the [startIndex] and [endIndex] to report an error, and
    * don't append anything to the builder, if the code point is invalid. The
@@ skipping 331 matching lines @@
   }
 
   bool _injectGenericComment(TokenType type, int prefixLen) {
     if (parseGenericMethodComments) {
       CommentToken t = _currentToken.precedingComments;
       for (; t != null; t = t.next) {
         if (t.type == type) {
           String comment = t.lexeme.substring(prefixLen, t.lexeme.length - 2);
           Token list = _scanGenericMethodComment(comment, t.offset + prefixLen);
           if (list != null) {
+            _reportErrorForToken(HintCode.GENERIC_METHOD_COMMENT, t);
             // Remove the token from the comment stream.
             t.remove();
             // Insert the tokens into the stream.
             _injectTokenList(list);
             return true;
           }
         }
       }
     }
     return false;
@@ skipping 2479 matching lines @@
     }
   }
 }
 
 /**
  * Instances of this class are thrown when the parser detects that AST has
  * too many nested expressions to be parsed safely and avoid possibility of
  * [StackOverflowError] in the parser or during later analysis.
  */
 class _TooDeepTreeError {}