Clean up parser comments

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.
 
 // This code was auto-generated, is not intended to be edited, and is subject to
 // significant change. Please see the README file for more information.
 
 library engine.parser;
 
 import "dart:math" as math;
@@ skipping 409 matching lines @@
 
 Object invokeParserMethodImpl(
     Parser parser, String methodName, List<Object> objects, Token tokenStream) {
   parser.currentToken = tokenStream;
   MethodTrampoline method =
       methodTable_Parser['${methodName}_${objects.length}'];
   return method.invoke(parser, objects);
 }
 
 /**
- * Instances of the class `CommentAndMetadata` implement a simple data-holder for a method
- * that needs to return multiple values.
+ * A simple data-holder for a method that needs to return multiple values.
  */
 class CommentAndMetadata {
   /**
    * The documentation comment that was parsed, or `null` if none was given.
    */
   final Comment comment;
 
   /**
    * The metadata that was parsed.
    */
   final List<Annotation> metadata;
 
   /**
-   * Initialize a newly created holder with the given data.
-   *
-   * @param comment the documentation comment that was parsed
-   * @param metadata the metadata that was parsed
+   * Initialize a newly created holder with the given [comment] and [metadata].
    */
   CommentAndMetadata(this.comment, this.metadata);
 }
 
 /**
- * Instances of the class `FinalConstVarOrType` implement a simple data-holder for a method
- * that needs to return multiple values.
+ * A simple data-holder for a method that needs to return multiple values.
  */
 class FinalConstVarOrType {
   /**
    * The 'final', 'const' or 'var' keyword, or `null` if none was given.
    */
   final Token keyword;
 
   /**
    * The type, of `null` if no type was specified.
    */
   final TypeName type;
 
   /**
-   * Initialize a newly created holder with the given data.
-   *
-   * @param keyword the 'final', 'const' or 'var' keyword
-   * @param type the type
+   * Initialize a newly created holder with the given [keyword] and [type].
    */
   FinalConstVarOrType(this.keyword, this.type);
 }
 
 /**
- * Instances of the class `IncrementalParseDispatcher` implement a dispatcher that will invoke
- * the right parse method when re-parsing a specified child of the visited node. All of the methods
- * in this class assume that the parser is positioned to parse the replacement for the node. All of
- * the methods will throw an [IncrementalParseException] if the node could not be parsed for
- * some reason.
+ * A dispatcher that will invoke the right parse method when re-parsing a
+ * specified child of the visited node. All of the methods in this class assume
+ * that the parser is positioned to parse the replacement for the node. All of
+ * the methods will throw an [IncrementalParseException] if the node could not
+ * be parsed for some reason.
  */
 class IncrementalParseDispatcher implements AstVisitor<AstNode> {
   /**
    * The parser used to parse the replacement for the node.
    */
   final Parser _parser;
 
   /**
    * The node that is to be replaced.
    */
   final AstNode _oldNode;
 
   /**
-   * Initialize a newly created dispatcher to parse a single node that will replace the given node.
-   *
-   * @param parser the parser used to parse the replacement for the node
-   * @param oldNode the node that is to be replaced
+   * Initialize a newly created dispatcher to parse a single node that will
+   * use the [_parser] to replace the [_oldNode].
    */
   IncrementalParseDispatcher(this._parser, this._oldNode);
 
   @override
   AstNode visitAdjacentStrings(AdjacentStrings node) {
     if (node.strings.contains(_oldNode)) {
       return _parser.parseStringLiteral();
     }
     return _notAChild(node);
   }
@@ skipping 1049 matching lines @@
 
   @override
   AstNode visitYieldStatement(YieldStatement node) {
     if (identical(_oldNode, node.expression)) {
       return _parser.parseExpression2();
     }
     return _notAChild(node);
   }
 
   /**
-   * Return `true` if the given assignment expression can have a cascade expression on the
-   * right-hand side.
-   *
-   * @param node the assignment expression being tested
-   * @return `true` if the right-hand side can be a cascade expression
+   * Return `true` if the given assignment [expression] can have a cascade
+   * expression on the right-hand side.
    */
-  bool _isCascadeAllowedInAssignment(AssignmentExpression node) {
+  bool _isCascadeAllowedInAssignment(AssignmentExpression expression) {
     // TODO(brianwilkerson) Implement this method.
     throw new InsufficientContextException();
   }
 
   /**
-   * Return `true` if the given throw expression can have a cascade expression.
-   *
-   * @param node the throw expression being tested
-   * @return `true` if the expression can be a cascade expression
+   * Return `true` if the given throw [expression] can have a cascade
+   * expression.
    */
-  bool _isCascadeAllowedInThrow(ThrowExpression node) {
+  bool _isCascadeAllowedInThrow(ThrowExpression expression) {
     // TODO(brianwilkerson) Implement this method.
     throw new InsufficientContextException();
   }
 
   /**
-   * Throw an exception indicating that the visited node was not the parent of the node to be
-   * replaced.
-   *
-   * @param visitedNode the visited node that should have been the parent of the node to be replaced
+   * Throw an exception indicating that the visited [node] was not the parent of
+   * the node to be replaced.
    */
-  AstNode _notAChild(AstNode visitedNode) {
+  AstNode _notAChild(AstNode node) {
     throw new IncrementalParseException.con1(
-        "Internal error: the visited node (a ${visitedNode.runtimeType}) was not the parent of the node to be replaced (a ${_oldNode.runtimeType})");
+        "Internal error: the visited node (a ${node.runtimeType}) was not the parent of the node to be replaced (a ${_oldNode.runtimeType})");
   }
 }
 
 /**
- * Instances of the class `IncrementalParseException` represent an exception that occurred
- * while attempting to parse a replacement for a specified node in an existing AST structure.
+ * An exception that occurred while attempting to parse a replacement for a
+ * specified node in an existing AST structure.
  */
 class IncrementalParseException extends RuntimeException {
   /**
-   * Initialize a newly created exception to have no message and to be its own cause.
+   * Initialize a newly created exception to have no message and to be its own
+   * cause.
    */
   IncrementalParseException() : super();
 
   /**
-   * Initialize a newly created exception to have the given message and to be its own cause.
-   *
-   * @param message the message describing the reason for the exception
+   * Initialize a newly created exception to have the given [message] and to be
+   * its own cause.
    */
   IncrementalParseException.con1(String message) : super(message: message);
 
   /**
-   * Initialize a newly created exception to have no message and to have the given cause.
-   *
-   * @param cause the exception that caused this exception
+   * Initialize a newly created exception to have no message and to have the
+   * given [cause].
    */
   IncrementalParseException.con2(Exception cause) : super(cause: cause);
 }
 
 /**
- * Instances of the class `IncrementalParser` re-parse a single AST structure within a larger
- * AST structure.
+ * An object used to re-parse a single AST structure within a larger AST
+ * structure.
  */
 class IncrementalParser {
   /**
    * The source being parsed.
    */
   final Source _source;
 
   /**
    * A map from old tokens to new tokens used during the cloning process.
    */
   final TokenMap _tokenMap;
 
   /**
-   * The error listener that will be informed of any errors that are found during the parse.
+   * The error listener that will be informed of any errors that are found
+   * during the parse.
    */
   final AnalysisErrorListener _errorListener;
 
   /**
    * The node in the AST structure that contains the revised content.
    */
   AstNode _updatedNode;
 
   /**
-   * Initialize a newly created incremental parser to parse a portion of the content of the given
-   * source.
-   *
-   * @param source the source being parsed
-   * @param tokenMap a map from old tokens to new tokens used during the cloning process
-   * @param errorListener the error listener that will be informed of any errors that are found
-   *          during the parse
+   * Initialize a newly created incremental parser to parse a portion of the
+   * content of the given [_source]. The [_tokenMap] is a map from old tokens to
+   * new tokens that is used during the cloning process. The [_errorListener]
+   * will be informed of any errors that are found during the parse.
    */
   IncrementalParser(this._source, this._tokenMap, this._errorListener);
 
   /**
    * Return the node in the AST structure that contains the revised content.
-   *
-   * @return the updated node
    */
   AstNode get updatedNode => _updatedNode;
 
   /**
-   * Given a range of tokens that were re-scanned, re-parse the minimum number of tokens to produce
-   * a consistent AST structure. The range is represented by the first and last tokens in the range.
+   * Given a range of tokens that were re-scanned, re-parse the minimum number
+   * of tokens to produce a consistent AST structure. The range is represented
+   * by the first and last tokens in the range.
+   *
+   * More specifically, the [leftToken] is the token in the new token stream
+   * immediately to the left of the range of tokens that were inserted and the
+   * [rightToken] is the token in the new token stream immediately to the right
+   * of the range of tokens that were inserted. The [originalStart] and
+   * [originalEnd] are the offsets in the original source of the first and last
+   * characters that were modified.
+   *
    * The tokens are assumed to be contained in the same token stream.
-   *
-   * @param leftToken the token in the new token stream immediately to the left of the range of
-   *          tokens that were inserted
-   * @param rightToken the token in the new token stream immediately to the right of the range of
-   *          tokens that were inserted
-   * @param originalStart the offset in the original source of the first character that was modified
-   * @param originalEnd the offset in the original source of the last character that was modified
    */
   AstNode reparse(AstNode originalStructure, Token leftToken, Token rightToken,
       int originalStart, int originalEnd) {
     AstNode oldNode = null;
     AstNode newNode = null;
     //
     // Find the first token that needs to be re-parsed.
     //
     Token firstToken = leftToken.next;
     if (identical(firstToken, rightToken)) {
@@ skipping 74 matching lines @@
       ResolutionCopier.copyResolutionData(oldNode, newNode);
       return newNode;
     }
     ResolutionCopier.copyResolutionData(oldNode, newNode);
     IncrementalAstCloner cloner =
         new IncrementalAstCloner(oldNode, newNode, _tokenMap);
     return originalStructure.accept(cloner) as AstNode;
   }
 
   /**
-   * Return the first (non-EOF) token in the token stream containing the given token.
-   *
-   * @param firstToken the token from which the search is to begin
-   * @return the first token in the token stream containing the given token
+   * Return the first (non-EOF) token in the token stream containing the
+   * [firstToken].
    */
   Token _findFirstToken(Token firstToken) {
     while (firstToken.type != TokenType.EOF) {
       firstToken = firstToken.previous;
     }
     return firstToken.next;
   }
 
   /**
-   * Find the token at or before the given token with the given offset, or `null` if there is
-   * no such token.
-   *
-   * @param firstToken the token from which the search is to begin
-   * @param offset the offset of the token to be returned
-   * @return the token with the given offset
+   * Find the token at or before the [firstToken] with the given [offset], or
+   * `null` if there is no such token.
    */
   Token _findTokenAt(Token firstToken, int offset) {
     while (firstToken.offset > offset && firstToken.type != TokenType.EOF) {
       firstToken = firstToken.previous;
     }
     return firstToken;
   }
 }
 
 /**
- * Visitor capable of inferring the correct parser state for incremental
+ * A visitor capable of inferring the correct parser state for incremental
  * parsing.  This visitor visits each parent/child relationship in the chain of
  * ancestors of the node to be replaced (starting with the root of the parse
  * tree), updating the parser to the correct state for parsing the child of the
  * given parent.  Once it has visited all of these relationships, the parser
  * will be in the correct state for reparsing the node to be replaced.
- *
- * TODO(paulberry): add support for other pieces of parser state (_inAsync,
- * _inGenerator, _inLoop, and _inSwitch).  Note that _inLoop and _inSwitch only
- * affect error message generation.
  */
 class IncrementalParseStateBuilder extends SimpleAstVisitor {
+  // TODO(paulberry): add support for other pieces of parser state (_inAsync,
+  // _inGenerator, _inLoop, and _inSwitch).  Note that _inLoop and _inSwitch
+  // only affect error message generation.
+
   /**
    * The parser whose state should be built.
    */
   final Parser _parser;
 
   /**
    * The child node in the parent/child relationship currently being visited.
    * (The corresponding parent is the node passed to the visit...() function.)
    */
   AstNode _childNode;
@@ skipping 62 matching lines @@
 
   @override
   void visitParenthesizedExpression(ParenthesizedExpression node) {
     if (identical(_childNode, node.expression)) {
       _parser._inInitializer = false;
     }
   }
 }
 
 /**
- * Instances of the class `InsufficientContextException` represent a situation in which an AST
- * node cannot be re-parsed because there is not enough context to know how to re-parse the node.
- * Clients can attempt to re-parse the parent of the node.
+ * An exception indicating that an AST node cannot be re-parsed because there is
+ * not enough context to know how to re-parse the node. Clients can attempt to
+ * re-parse the parent of the node.
  */
 class InsufficientContextException extends IncrementalParseException {
   /**
-   * Initialize a newly created exception to have no message and to be its own cause.
+   * Initialize a newly created exception to have no message and to be its own
+   * cause.
    */
   InsufficientContextException() : super();
 
   /**
-   * Initialize a newly created exception to have the given message and to be its own cause.
-   *
-   * @param message the message describing the reason for the exception
+   * Initialize a newly created exception to have the given [message] and to be
+   * its own cause.
    */
   InsufficientContextException.con1(String message) : super.con1(message);
 
   /**
-   * Initialize a newly created exception to have no message and to have the given cause.
-   *
-   * @param cause the exception that caused this exception
+   * Initialize a newly created exception to have no message and to have the
+   * given [cause].
    */
   InsufficientContextException.con2(Exception cause) : super.con2(cause);
 }
 
 /**
- * Wrapper around [Function] which should be called with "target" and "arguments".
+ * Wrapper around [Function] which should be called with "target" and
+ * "arguments".
  */
 class MethodTrampoline {
   int parameterCount;
   Function trampoline;
   MethodTrampoline(this.parameterCount, this.trampoline);
   Object invoke(target, List arguments) {
     if (arguments.length != parameterCount) {
       throw new IllegalArgumentException(
           "${arguments.length} != $parameterCount");
     }
     switch (parameterCount) {
       case 0:
         return trampoline(target);
       case 1:
         return trampoline(target, arguments[0]);
       case 2:
         return trampoline(target, arguments[0], arguments[1]);
       case 3:
         return trampoline(target, arguments[0], arguments[1], arguments[2]);
       case 4:
         return trampoline(
             target, arguments[0], arguments[1], arguments[2], arguments[3]);
       default:
         throw new IllegalArgumentException("Not implemented for > 4 arguments");
     }
   }
 }
 
 /**
- * Instances of the class `Modifiers` implement a simple data-holder for a method that needs
- * to return multiple values.
+ * A simple data-holder for a method that needs to return multiple values.
  */
 class Modifiers {
   /**
-   * The token representing the keyword 'abstract', or `null` if the keyword was not found.
+   * The token representing the keyword 'abstract', or `null` if the keyword was
+   * not found.
    */
   Token abstractKeyword;
 
   /**
-   * The token representing the keyword 'const', or `null` if the keyword was not found.
+   * The token representing the keyword 'const', or `null` if the keyword was
+   * not found.
    */
   Token constKeyword;
 
   /**
-   * The token representing the keyword 'external', or `null` if the keyword was not found.
+   * The token representing the keyword 'external', or `null` if the keyword was
+   * not found.
    */
   Token externalKeyword;
 
   /**
-   * The token representing the keyword 'factory', or `null` if the keyword was not found.
+   * The token representing the keyword 'factory', or `null` if the keyword was
+   * not found.
    */
   Token factoryKeyword;
 
   /**
-   * The token representing the keyword 'final', or `null` if the keyword was not found.
+   * The token representing the keyword 'final', or `null` if the keyword was
+   * not found.
    */
   Token finalKeyword;
 
   /**
-   * The token representing the keyword 'static', or `null` if the keyword was not found.
+   * The token representing the keyword 'static', or `null` if the keyword was
+   * not found.
    */
   Token staticKeyword;
 
   /**
-   * The token representing the keyword 'var', or `null` if the keyword was not found.
+   * The token representing the keyword 'var', or `null` if the keyword was not
+   * found.
    */
   Token varKeyword;
 
   @override
   String toString() {
     StringBuffer buffer = new StringBuffer();
     bool needsSpace = _appendKeyword(buffer, false, abstractKeyword);
     needsSpace = _appendKeyword(buffer, needsSpace, constKeyword);
     needsSpace = _appendKeyword(buffer, needsSpace, externalKeyword);
     needsSpace = _appendKeyword(buffer, needsSpace, factoryKeyword);
     needsSpace = _appendKeyword(buffer, needsSpace, finalKeyword);
     needsSpace = _appendKeyword(buffer, needsSpace, staticKeyword);
     _appendKeyword(buffer, needsSpace, varKeyword);
     return buffer.toString();
   }
 
   /**
-   * If the given keyword is not `null`, append it to the given builder, prefixing it with a
-   * space if needed.
-   *
-   * @param builder the builder to which the keyword will be appended
-   * @param needsSpace `true` if the keyword needs to be prefixed with a space
-   * @param keyword the keyword to be appended
-   * @return `true` if subsequent keywords need to be prefixed with a space
+   * If the given [keyword] is not `null`, append it to the given [builder],
+   * prefixing it with a space if [needsSpace] is `true`. Return `true` if
+   * subsequent keywords need to be prefixed with a space.
    */
   bool _appendKeyword(StringBuffer buffer, bool needsSpace, Token keyword) {
     if (keyword != null) {
       if (needsSpace) {
         buffer.writeCharCode(0x20);
       }
       buffer.write(keyword.lexeme);
       return true;
     }
     return needsSpace;
   }
 }
 
 /**
- * Instances of the class `Parser` are used to parse tokens into an AST structure.
+ * A parser used to parse tokens into an AST structure.
  */
 class Parser {
   static String ASYNC = "async";
 
   static String _AWAIT = "await";
 
   static String _HIDE = "hide";
 
   static String _OF = "of";
 
   static String _ON = "on";
 
   static String _NATIVE = "native";
 
   static String _SHOW = "show";
 
   static String SYNC = "sync";
 
   static String _YIELD = "yield";
 
   /**
    * The source being parsed.
    */
   final Source _source;
 
   /**
-   * The error listener that will be informed of any errors that are found during the parse.
+   * The error listener that will be informed of any errors that are found
+   * during the parse.
    */
   final AnalysisErrorListener _errorListener;
 
   /**
    * An [errorListener] lock, if more than `0`, then errors are not reported.
    */
   int _errorListenerLock = 0;
 
   /**
    * A flag indicating whether parser is to parse function bodies.
    */
   bool _parseFunctionBodies = true;
 
   /**
    * The next token to be parsed.
    */
   Token _currentToken;
 
   /**
-   * A flag indicating whether the parser is currently in a function body marked as being 'async'.
+   * A flag indicating whether the parser is currently in a function body marked
+   * as being 'async'.
    */
   bool _inAsync = false;
 
   /**
-   * A flag indicating whether the parser is currently in a function body marked as being 'async'.
+   * A flag indicating whether the parser is currently in a function body marked
+   * as being 'async'.
    */
   bool _inGenerator = false;
 
   /**
    * A flag indicating whether the parser is currently in the body of a loop.
    */
   bool _inLoop = false;
 
   /**
    * A flag indicating whether the parser is currently in a switch statement.
    */
   bool _inSwitch = false;
 
   /**
-   * A flag indicating whether the parser is currently in a constructor field initializer, with no
-   * intervening parens, braces, or brackets.
+   * A flag indicating whether the parser is currently in a constructor field
+   * initializer, with no intervening parens, braces, or brackets.
    */
   bool _inInitializer = false;
 
   /**
-   * Initialize a newly created parser.
-   *
-   * @param source the source being parsed
-   * @param errorListener the error listener that will be informed of any errors that are found
-   *          during the parse
+   * Initialize a newly created parser to parse the content of the given
+   * [_source] and to report any errors that are found to the given
+   * [_errorListener].
    */
   Parser(this._source, this._errorListener);
 
   void set currentToken(Token currentToken) {
     this._currentToken = currentToken;
   }
 
   /**
-   * Return `true` if the current token is the first token of a return type that is followed
-   * by an identifier, possibly followed by a list of type parameters, followed by a
-   * left-parenthesis. This is used by parseTypeAlias to determine whether or not to parse a return
-   * type.
-   *
-   * @return `true` if we can successfully parse the rest of a type alias if we first parse a
-   *         return type.
+   * Return `true` if the current token is the first token of a return type that
+   * is followed by an identifier, possibly followed by a list of type
+   * parameters, followed by a left-parenthesis. This is used by
+   * [_parseTypeAlias] to determine whether or not to parse a return type.
    */
   bool get hasReturnTypeInTypeAlias {
     Token next = _skipReturnType(_currentToken);
     if (next == null) {
       return false;
     }
     return _tokenMatchesIdentifier(next);
   }
 
   /**
    * Set whether the parser is to parse the async support.
-   *
-   * @param parseAsync `true` if the parser is to parse the async support
    */
+  @deprecated
   void set parseAsync(bool parseAsync) {
     // Async support cannot be disabled
   }
 
   /**
    * Set whether the parser is to parse deferred libraries.
-   *
-   * @param parseDeferredLibraries `true` if the parser is to parse deferred libraries
    */
+  @deprecated
   void set parseDeferredLibraries(bool parseDeferredLibraries) {
     // Deferred libraries support cannot be disabled
   }
 
   /**
    * Set whether the parser is to parse enum declarations.
-   *
-   * @param parseEnum `true` if the parser is to parse enum declarations
    */
+  @deprecated
   void set parseEnum(bool parseEnum) {
     // Enum support cannot be disabled
   }
 
   /**
    * Set whether parser is to parse function bodies.
-   *
-   * @param parseFunctionBodies `true` if parser is to parse function bodies
    */
   void set parseFunctionBodies(bool parseFunctionBodies) {
     this._parseFunctionBodies = parseFunctionBodies;
   }
 
   /**
    * Advance to the next token in the token stream, making it the new current
    * token and return the token that was current before this method was invoked.
    */
   Token getAndAdvance() {
     Token token = _currentToken;
     _advance();
     return token;
   }
 
   /**
-   * Parse an annotation.
+   * Parse an annotation. Return the annotation that was parsed.
    *
-   * <pre>
-   * annotation ::=
-   *     '@' qualified ('.' identifier)? arguments?
-   * </pre>
+   *     annotation ::=
+   *         '@' qualified ('.' identifier)? arguments?
    *
-   * @return the annotation that was parsed
    */
   Annotation parseAnnotation() {
     Token atSign = _expect(TokenType.AT);
     Identifier name = parsePrefixedIdentifier();
     Token period = null;
     SimpleIdentifier constructorName = null;
     if (_matches(TokenType.PERIOD)) {
       period = getAndAdvance();
       constructorName = parseSimpleIdentifier();
     }
     ArgumentList arguments = null;
     if (_matches(TokenType.OPEN_PAREN)) {
       arguments = parseArgumentList();
     }
     return new Annotation(atSign, name, period, constructorName, arguments);
   }
 
   /**
-   * Parse an argument.
+   * Parse an argument. Return the argument that was parsed.
    *
-   * <pre>
-   * argument ::=
-   *     namedArgument
-   *   | expression
+   *     argument ::=
+   *         namedArgument
+   *       | expression
    *
-   * namedArgument ::=
-   *     label expression
-   * </pre>
-   *
-   * @return the argument that was parsed
+   *     namedArgument ::=
+   *         label expression
    */
   Expression parseArgument() {
     //
     // Both namedArgument and expression can start with an identifier, but only
     // namedArgument can have an identifier followed by a colon.
     //
     if (_matchesIdentifier() && _tokenMatches(_peek(), TokenType.COLON)) {
       return new NamedExpression(parseLabel(), parseExpression2());
     } else {
       return parseExpression2();
     }
   }
 
   /**
-   * Parse a list of arguments.
+   * Parse a list of arguments. Return the argument list that was parsed.
    *
-   * <pre>
-   * arguments ::=
-   *     '(' argumentList? ')'
+   *     arguments ::=
+   *         '(' argumentList? ')'
    *
-   * argumentList ::=
-   *     namedArgument (',' namedArgument)*
-   *   | expressionList (',' namedArgument)*
-   * </pre>
-   *
-   * @return the argument list that was parsed
+   *     argumentList ::=
+   *         namedArgument (',' namedArgument)*
+   *       | expressionList (',' namedArgument)*
    */
   ArgumentList parseArgumentList() {
     Token leftParenthesis = _expect(TokenType.OPEN_PAREN);
     List<Expression> arguments = new List<Expression>();
     if (_matches(TokenType.CLOSE_PAREN)) {
       return new ArgumentList(leftParenthesis, arguments, getAndAdvance());
     }
     //
     // Even though unnamed arguments must all appear before any named arguments,
     // we allow them to appear in any order so that we can recover faster.
@@ skipping 27 matching lines @@
       // whether there is a matching right parenthesis. If there is, then we're
       // more likely missing a comma and should go back to parsing arguments.
       Token rightParenthesis = _expect(TokenType.CLOSE_PAREN);
       return new ArgumentList(leftParenthesis, arguments, rightParenthesis);
     } finally {
       _inInitializer = wasInInitializer;
     }
   }
 
   /**
-   * Parse a bitwise or expression.
+   * Parse a bitwise or expression. Return the bitwise or expression that was
+   * parsed.
    *
-   * <pre>
-   * bitwiseOrExpression ::=
-   *     bitwiseXorExpression ('|' bitwiseXorExpression)*
-   *   | 'super' ('|' bitwiseXorExpression)+
-   * </pre>
-   *
-   * @return the bitwise or expression that was parsed
+   *     bitwiseOrExpression ::=
+   *         bitwiseXorExpression ('|' bitwiseXorExpression)*
+   *       | 'super' ('|' bitwiseXorExpression)+
    */
   Expression parseBitwiseOrExpression() {
     Expression expression;
     if (_matchesKeyword(Keyword.SUPER) &&
         _tokenMatches(_peek(), TokenType.BAR)) {
       expression = new SuperExpression(getAndAdvance());
     } else {
       expression = _parseBitwiseXorExpression();
     }
     while (_matches(TokenType.BAR)) {
       Token operator = getAndAdvance();
       expression = new BinaryExpression(
           expression, operator, _parseBitwiseXorExpression());
     }
     return expression;
   }
 
   /**
-   * Parse a block.
+   * Parse a block. Return the block that was parsed.
    *
-   * <pre>
-   * block ::=
-   *     '{' statements '}'
-   * </pre>
-   *
-   * @return the block that was parsed
+   *     block ::=
+   *         '{' statements '}'
    */
   Block parseBlock() {
     Token leftBracket = _expect(TokenType.OPEN_CURLY_BRACKET);
     List<Statement> statements = new List<Statement>();
     Token statementStart = _currentToken;
     while (
         !_matches(TokenType.EOF) && !_matches(TokenType.CLOSE_CURLY_BRACKET)) {
       Statement statement = parseStatement2();
       if (statement != null) {
         statements.add(statement);
       }
       if (identical(_currentToken, statementStart)) {
         // Ensure that we are making progress and report an error if we're not.
         _reportErrorForToken(ParserErrorCode.UNEXPECTED_TOKEN, _currentToken,
             [_currentToken.lexeme]);
         _advance();
       }
       statementStart = _currentToken;
     }
     Token rightBracket = _expect(TokenType.CLOSE_CURLY_BRACKET);
     return new Block(leftBracket, statements, rightBracket);
   }
 
   /**
-   * Parse a class member.
+   * Parse a class member. The [className] is the name of the class containing
+   * the member being parsed. Return the class member that was parsed, or `null`
+   * if what was found was not a valid class member.
    *
-   * <pre>
-   * classMemberDefinition ::=
-   *     declaration ';'
-   *   | methodSignature functionBody
-   * </pre>
-   *
-   * @param className the name of the class containing the member being parsed
-   * @return the class member that was parsed, or `null` if what was found was not a valid
-   *         class member
+   *     classMemberDefinition ::=
+   *         declaration ';'
+   *       | methodSignature functionBody
    */
   ClassMember parseClassMember(String className) {
     CommentAndMetadata commentAndMetadata = _parseCommentAndMetadata();
     Modifiers modifiers = _parseModifiers();
     if (_matchesKeyword(Keyword.VOID)) {
       TypeName returnType = parseReturnType();
       if (_matchesKeyword(Keyword.GET) && _tokenMatchesIdentifier(_peek())) {
         _validateModifiersForGetterOrSetterOrMethod(modifiers);
         return _parseGetter(commentAndMetadata, modifiers.externalKeyword,
             modifiers.staticKeyword, returnType);
@@ skipping 237 matching lines @@
       _currentToken = _injectToken(
           new Parser_SyntheticKeywordToken(Keyword.GET, _currentToken.offset));
       return _parseGetter(commentAndMetadata, modifiers.externalKeyword,
           modifiers.staticKeyword, type);
     }
     return _parseInitializedIdentifierList(commentAndMetadata,
         modifiers.staticKeyword, _validateModifiersForField(modifiers), type);
   }
 
   /**
-   * Parse a single import combinator.  If no combinator is found, return
-   * `null`.
+   * Parse a single combinator. Return the combinator that was parsed, or `null`
+   * if no combinator is found.
    *
-   * <pre>
-   * combinator ::=
-   *     'show' identifier (',' identifier)*
-   *   | 'hide' identifier (',' identifier)*
-   * </pre>
+   *     combinator ::=
+   *         'show' identifier (',' identifier)*
+   *       | 'hide' identifier (',' identifier)*
    */
   Combinator parseCombinator() {
     if (_matchesString(_SHOW) || _matchesString(_HIDE)) {
       Token keyword = getAndAdvance();
       List<SimpleIdentifier> names = _parseIdentifierList();
       if (keyword.lexeme == _SHOW) {
         return new ShowCombinator(keyword, names);
       } else {
         return new HideCombinator(keyword, names);
       }
     }
     return null;
   }
 
   /**
-   * Parse a compilation unit, starting with the given token.
-   *
-   * @param token the first token of the compilation unit
-   * @return the compilation unit that was parsed
+   * Parse a compilation unit, starting with the given [token]. Return the
+   * compilation unit that was parsed.
    */
   CompilationUnit parseCompilationUnit(Token token) {
     _currentToken = token;
     return parseCompilationUnit2();
   }
 
   /**
-   * Parse a compilation unit.
+   * Parse a compilation unit. Return the compilation unit that was parsed.
    *
    * Specified:
    *
-   * <pre>
-   * compilationUnit ::=
-   *     scriptTag? directive* topLevelDeclaration*
-   * </pre>
+   *     compilationUnit ::=
+   *         scriptTag? directive* topLevelDeclaration*
+   *
    * Actual:
    *
-   * <pre>
-   * compilationUnit ::=
-   *     scriptTag? topLevelElement*
+   *     compilationUnit ::=
+   *         scriptTag? topLevelElement*
    *
-   * topLevelElement ::=
-   *     directive
-   *   | topLevelDeclaration
-   * </pre>
-   *
-   * @return the compilation unit that was parsed
+   *     topLevelElement ::=
+   *         directive
+   *       | topLevelDeclaration
    */
   CompilationUnit parseCompilationUnit2() {
     Token firstToken = _currentToken;
     ScriptTag scriptTag = null;
     if (_matches(TokenType.SCRIPT_TAG)) {
       scriptTag = new ScriptTag(getAndAdvance());
     }
     //
     // Even though all directives must appear before declarations and must occur
     // in a given order, we allow directives and declarations to occur in any
@@ skipping 11 matching lines @@
       CommentAndMetadata commentAndMetadata = _parseCommentAndMetadata();
       if ((_matchesKeyword(Keyword.IMPORT) ||
               _matchesKeyword(Keyword.EXPORT) ||
               _matchesKeyword(Keyword.LIBRARY) ||
               _matchesKeyword(Keyword.PART)) &&
           !_tokenMatches(_peek(), TokenType.PERIOD) &&
           !_tokenMatches(_peek(), TokenType.LT) &&
           !_tokenMatches(_peek(), TokenType.OPEN_PAREN)) {
         Directive directive = _parseDirective(commentAndMetadata);
         if (declarations.length > 0 && !directiveFoundAfterDeclaration) {
-          _reportErrorForToken(
-              ParserErrorCode.DIRECTIVE_AFTER_DECLARATION, directive.beginToken);
+          _reportErrorForToken(ParserErrorCode.DIRECTIVE_AFTER_DECLARATION,
+              directive.beginToken);
           directiveFoundAfterDeclaration = true;
         }
         if (directive is LibraryDirective) {
           if (libraryDirectiveFound) {
             _reportErrorForCurrentToken(
                 ParserErrorCode.MULTIPLE_LIBRARY_DIRECTIVES);
           } else {
             if (directives.length > 0) {
               _reportErrorForToken(ParserErrorCode.LIBRARY_DIRECTIVE_NOT_FIRST,
                   directive.libraryKeyword);
@@ skipping 55 matching lines @@
           _advance();
         }
       }
       memberStart = _currentToken;
     }
     return new CompilationUnit(
         firstToken, scriptTag, directives, declarations, _currentToken);
   }
 
   /**
-   * Parse a conditional expression.
+   * Parse a conditional expression. Return the conditional expression that was
+   * parsed.
    *
-   * <pre>
-   * conditionalExpression ::=
-   *     logicalOrExpression ('?' expressionWithoutCascade ':' expressionWithoutCascade)?
-   * </pre>
-   *
-   * @return the conditional expression that was parsed
+   *     conditionalExpression ::=
+   *         logicalOrExpression ('?' expressionWithoutCascade ':' expressionWithoutCascade)?
    */
   Expression parseConditionalExpression() {
     Expression condition = parseLogicalOrExpression();
     if (!_matches(TokenType.QUESTION)) {
       return condition;
     }
     Token question = getAndAdvance();
     Expression thenExpression = parseExpressionWithoutCascade();
     Token colon = _expect(TokenType.COLON);
     Expression elseExpression = parseExpressionWithoutCascade();
     return new ConditionalExpression(
         condition, question, thenExpression, colon, elseExpression);
   }
 
   /**
-   * Parse the name of a constructor.
+   * Parse the name of a constructor. Return the constructor name that was
+   * parsed.
    *
-   * <pre>
-   * constructorName:
-   *     type ('.' identifier)?
-   * </pre>
-   *
-   * @return the constructor name that was parsed
+   *     constructorName:
+   *         type ('.' identifier)?
    */
   ConstructorName parseConstructorName() {
     TypeName type = parseTypeName();
     Token period = null;
     SimpleIdentifier name = null;
     if (_matches(TokenType.PERIOD)) {
       period = getAndAdvance();
       name = parseSimpleIdentifier();
     }
     return new ConstructorName(type, period, name);
   }
 
   /**
-   * Parse the script tag and directives in a compilation unit, starting with the given token, until
-   * the first non-directive is encountered. The remainder of the compilation unit will not be
-   * parsed. Specifically, if there are directives later in the file, they will not be parsed.
-   *
-   * @param token the first token of the compilation unit
-   * @return the compilation unit that was parsed
+   * Parse the script tag and directives in a compilation unit, starting with
+   * the given [token], until the first non-directive is encountered. The
+   * remainder of the compilation unit will not be parsed. Specifically, if
+   * there are directives later in the file, they will not be parsed. Return the
+   * compilation unit that was parsed.
    */
   CompilationUnit parseDirectives(Token token) {
     _currentToken = token;
     return _parseDirectives();
   }
 
   /**
-   * Parse an expression, starting with the given token.
-   *
-   * @param token the first token of the expression
-   * @return the expression that was parsed, or `null` if the tokens do not represent a
-   *         recognizable expression
+   * Parse an expression, starting with the given [token]. Return the expression
+   * that was parsed, or `null` if the tokens do not represent a recognizable
+   * expression.
    */
   Expression parseExpression(Token token) {
     _currentToken = token;
     return parseExpression2();
   }
 
   /**
-   * Parse an expression that might contain a cascade.
+   * Parse an expression that might contain a cascade. Return the expression
+   * that was parsed.
    *
-   * <pre>
-   * expression ::=
-   *     assignableExpression assignmentOperator expression
-   *   | conditionalExpression cascadeSection*
-   *   | throwExpression
-   * </pre>
-   *
-   * @return the expression that was parsed
+   *     expression ::=
+   *         assignableExpression assignmentOperator expression
+   *       | conditionalExpression cascadeSection*
+   *       | throwExpression
    */
   Expression parseExpression2() {
     if (_matchesKeyword(Keyword.THROW)) {
       return _parseThrowExpression();
     } else if (_matchesKeyword(Keyword.RETHROW)) {
       // TODO(brianwilkerson) Rethrow is a statement again.
       return _parseRethrowExpression();
     }
     //
     // assignableExpression is a subset of conditionalExpression, so we can
@@ skipping 15 matching lines @@
       return new CascadeExpression(expression, cascadeSections);
     } else if (tokenType.isAssignmentOperator) {
       Token operator = getAndAdvance();
       _ensureAssignable(expression);
       return new AssignmentExpression(expression, operator, parseExpression2());
     }
     return expression;
   }
 
   /**
-   * Parse an expression that does not contain any cascades.
+   * Parse an expression that does not contain any cascades. Return the
+   * expression that was parsed.
    *
-   * <pre>
-   * expressionWithoutCascade ::=
-   *     assignableExpression assignmentOperator expressionWithoutCascade
-   *   | conditionalExpression
-   *   | throwExpressionWithoutCascade
-   * </pre>
-   *
-   * @return the expression that was parsed
+   *     expressionWithoutCascade ::=
+   *         assignableExpression assignmentOperator expressionWithoutCascade
+   *       | conditionalExpression
+   *       | throwExpressionWithoutCascade
    */
   Expression parseExpressionWithoutCascade() {
     if (_matchesKeyword(Keyword.THROW)) {
       return _parseThrowExpressionWithoutCascade();
     } else if (_matchesKeyword(Keyword.RETHROW)) {
       return _parseRethrowExpression();
     }
     //
     // assignableExpression is a subset of conditionalExpression, so we can
     // parse a conditional expression and then determine whether it is followed
     // by an assignmentOperator, checking for conformance to the restricted
     // grammar after making that determination.
     //
     Expression expression = parseConditionalExpression();
     if (_currentToken.type.isAssignmentOperator) {
       Token operator = getAndAdvance();
       _ensureAssignable(expression);
       expression = new AssignmentExpression(
           expression, operator, parseExpressionWithoutCascade());
     }
     return expression;
   }
 
   /**
-   * Parse a class extends clause.
+   * Parse a class extends clause. Return the class extends clause that was
+   * parsed.
    *
-   * <pre>
-   * classExtendsClause ::=
-   *     'extends' type
-   * </pre>
-   *
-   * @return the class extends clause that was parsed
+   *     classExtendsClause ::=
+   *         'extends' type
    */
   ExtendsClause parseExtendsClause() {
     Token keyword = _expectKeyword(Keyword.EXTENDS);
     TypeName superclass = parseTypeName();
     return new ExtendsClause(keyword, superclass);
   }
 
   /**
-   * Parse a list of formal parameters.
+   * Parse a list of formal parameters. Return the formal parameters that were
+   * parsed.
    *
-   * <pre>
-   * formalParameterList ::=
-   *     '(' ')'
-   *   | '(' normalFormalParameters (',' optionalFormalParameters)? ')'
-   *   | '(' optionalFormalParameters ')'
+   *     formalParameterList ::=
+   *         '(' ')'
+   *       | '(' normalFormalParameters (',' optionalFormalParameters)? ')'
+   *       | '(' optionalFormalParameters ')'
    *
-   * normalFormalParameters ::=
-   *     normalFormalParameter (',' normalFormalParameter)*
+   *     normalFormalParameters ::=
+   *         normalFormalParameter (',' normalFormalParameter)*
    *
-   * optionalFormalParameters ::=
-   *     optionalPositionalFormalParameters
-   *   | namedFormalParameters
+   *     optionalFormalParameters ::=
+   *         optionalPositionalFormalParameters
+   *       | namedFormalParameters
    *
-   * optionalPositionalFormalParameters ::=
-   *     '[' defaultFormalParameter (',' defaultFormalParameter)* ']'
+   *     optionalPositionalFormalParameters ::=
+   *         '[' defaultFormalParameter (',' defaultFormalParameter)* ']'
    *
-   * namedFormalParameters ::=
-   *     '{' defaultNamedParameter (',' defaultNamedParameter)* '}'
-   * </pre>
-   *
-   * @return the formal parameters that were parsed
+   *     namedFormalParameters ::=
+   *         '{' defaultNamedParameter (',' defaultNamedParameter)* '}'
    */
   FormalParameterList parseFormalParameterList() {
     Token leftParenthesis = _expect(TokenType.OPEN_PAREN);
     if (_matches(TokenType.CLOSE_PAREN)) {
       return new FormalParameterList(
           leftParenthesis, null, null, null, getAndAdvance());
     }
     //
     // Even though it is invalid to have default parameters outside of brackets,
     // required parameters inside of brackets, or multiple groups of default and
@@ skipping 135 matching lines @@
       leftSquareBracket = leftCurlyBracket;
     }
     if (rightSquareBracket == null) {
       rightSquareBracket = rightCurlyBracket;
     }
     return new FormalParameterList(leftParenthesis, parameters,
         leftSquareBracket, rightSquareBracket, rightParenthesis);
   }
 
   /**
-   * Parse a function expression.
+   * Parse a function expression. Return the function expression that was
+   * parsed.
    *
-   * <pre>
-   * functionExpression ::=
-   *     formalParameterList functionExpressionBody
-   * </pre>
-   *
-   * @return the function expression that was parsed
+   *     functionExpression ::=
+   *         formalParameterList functionExpressionBody
    */
   FunctionExpression parseFunctionExpression() {
     FormalParameterList parameters = parseFormalParameterList();
     _validateFormalParameterList(parameters);
     FunctionBody body =
         _parseFunctionBody(false, ParserErrorCode.MISSING_FUNCTION_BODY, true);
     return new FunctionExpression(parameters, body);
   }
 
   /**
-   * Parse an implements clause.
+   * Parse an implements clause. Return the implements clause that was parsed.
    *
-   * <pre>
-   * implementsClause ::=
-   *     'implements' type (',' type)*
-   * </pre>
-   *
-   * @return the implements clause that was parsed
+   *     implementsClause ::=
+   *         'implements' type (',' type)*
    */
   ImplementsClause parseImplementsClause() {
     Token keyword = _expectKeyword(Keyword.IMPLEMENTS);
     List<TypeName> interfaces = new List<TypeName>();
     interfaces.add(parseTypeName());
     while (_optional(TokenType.COMMA)) {
       interfaces.add(parseTypeName());
     }
     return new ImplementsClause(keyword, interfaces);
   }
 
   /**
-   * Parse a label.
+   * Parse a label. Return the label that was parsed.
    *
-   * <pre>
-   * label ::=
-   *     identifier ':'
-   * </pre>
-   *
-   * @return the label that was parsed
+   *     label ::=
+   *         identifier ':'
    */
   Label parseLabel() {
     SimpleIdentifier label = parseSimpleIdentifier();
     Token colon = _expect(TokenType.COLON);
     return new Label(label, colon);
   }
 
   /**
-   * Parse a library identifier.
+   * Parse a library identifier. Return the library identifier that was parsed.
    *
-   * <pre>
-   * libraryIdentifier ::=
-   *     identifier ('.' identifier)*
-   * </pre>
-   *
-   * @return the library identifier that was parsed
+   *     libraryIdentifier ::=
+   *         identifier ('.' identifier)*
    */
   LibraryIdentifier parseLibraryIdentifier() {
     List<SimpleIdentifier> components = new List<SimpleIdentifier>();
     components.add(parseSimpleIdentifier());
     while (_matches(TokenType.PERIOD)) {
       _advance();
       components.add(parseSimpleIdentifier());
     }
     return new LibraryIdentifier(components);
   }
 
   /**
-   * Parse a logical or expression.
+   * Parse a logical or expression. Return the logical or expression that was
+   * parsed.
    *
-   * <pre>
-   * logicalOrExpression ::=
-   *     logicalAndExpression ('||' logicalAndExpression)*
-   * </pre>
-   *
-   * @return the logical or expression that was parsed
+   *     logicalOrExpression ::=
+   *         logicalAndExpression ('||' logicalAndExpression)*
    */
   Expression parseLogicalOrExpression() {
     Expression expression = _parseLogicalAndExpression();
     while (_matches(TokenType.BAR_BAR)) {
       Token operator = getAndAdvance();
       expression = new BinaryExpression(
           expression, operator, _parseLogicalAndExpression());
     }
     return expression;
   }
 
   /**
-   * Parse a map literal entry.
+   * Parse a map literal entry. Return the map literal entry that was parsed.
    *
-   * <pre>
-   * mapLiteralEntry ::=
-   *     expression ':' expression
-   * </pre>
-   *
-   * @return the map literal entry that was parsed
+   *     mapLiteralEntry ::=
+   *         expression ':' expression
    */
   MapLiteralEntry parseMapLiteralEntry() {
     Expression key = parseExpression2();
     Token separator = _expect(TokenType.COLON);
     Expression value = parseExpression2();
     return new MapLiteralEntry(key, separator, value);
   }
 
   /**
-   * Parse a normal formal parameter and return the normal formal parameter that
+   * Parse a normal formal parameter. Return the normal formal parameter that
    * was parsed.
    *
-   * <pre>
-   * normalFormalParameter ::=
-   *     functionSignature
-   *   | fieldFormalParameter
-   *   | simpleFormalParameter
+   *     normalFormalParameter ::=
+   *         functionSignature
+   *       | fieldFormalParameter
+   *       | simpleFormalParameter
    *
-   * functionSignature:
-   *     metadata returnType? identifier formalParameterList
+   *     functionSignature:
+   *         metadata returnType? identifier formalParameterList
    *
-   * fieldFormalParameter ::=
-   *     metadata finalConstVarOrType? 'this' '.' identifier
+   *     fieldFormalParameter ::=
+   *         metadata finalConstVarOrType? 'this' '.' identifier
    *
-   * simpleFormalParameter ::=
-   *     declaredIdentifier
-   *   | metadata identifier
-   * </pre>
+   *     simpleFormalParameter ::=
+   *         declaredIdentifier
+   *       | metadata identifier
    */
   NormalFormalParameter parseNormalFormalParameter() {
     CommentAndMetadata commentAndMetadata = _parseCommentAndMetadata();
     FinalConstVarOrType holder = _parseFinalConstVarOrType(true);
     Token thisKeyword = null;
     Token period = null;
     if (_matchesKeyword(Keyword.THIS)) {
       thisKeyword = getAndAdvance();
       period = _expect(TokenType.PERIOD);
     }
@@ skipping 26 matching lines @@
     if (thisKeyword != null) {
       return new FieldFormalParameter(commentAndMetadata.comment,
           commentAndMetadata.metadata, holder.keyword, holder.type, thisKeyword,
           period, identifier, null);
     }
     return new SimpleFormalParameter(commentAndMetadata.comment,
         commentAndMetadata.metadata, holder.keyword, holder.type, identifier);
   }
 
   /**
-   * Parse a prefixed identifier.
+   * Parse a prefixed identifier. Return the prefixed identifier that was
+   * parsed.
    *
-   * <pre>
-   * prefixedIdentifier ::=
-   *     identifier ('.' identifier)?
-   * </pre>
-   *
-   * @return the prefixed identifier that was parsed
+   *     prefixedIdentifier ::=
+   *         identifier ('.' identifier)?
    */
   Identifier parsePrefixedIdentifier() {
     SimpleIdentifier qualifier = parseSimpleIdentifier();
     if (!_matches(TokenType.PERIOD)) {
       return qualifier;
     }
     Token period = getAndAdvance();
     SimpleIdentifier qualified = parseSimpleIdentifier();
     return new PrefixedIdentifier(qualifier, period, qualified);
   }
 
   /**
-   * Parse a return type.
+   * Parse a return type. Return the return type that was parsed.
    *
-   * <pre>
-   * returnType ::=
-   *     'void'
-   *   | type
-   * </pre>
-   *
-   * @return the return type that was parsed
+   *     returnType ::=
+   *         'void'
+   *       | type
    */
   TypeName parseReturnType() {
     if (_matchesKeyword(Keyword.VOID)) {
       return new TypeName(new SimpleIdentifier(getAndAdvance()), null);
     } else {
       return parseTypeName();
     }
   }
 
   /**
-   * Parse a simple identifier.
+   * Parse a simple identifier. Return the simple identifier that was parsed.
    *
-   * <pre>
-   * identifier ::=
-   *     IDENTIFIER
-   * </pre>
-   *
-   * @return the simple identifier that was parsed
+   *     identifier ::=
+   *         IDENTIFIER
    */
   SimpleIdentifier parseSimpleIdentifier() {
     if (_matchesIdentifier()) {
       String lexeme = _currentToken.lexeme;
       if ((_inAsync || _inGenerator) &&
           (lexeme == 'async' || lexeme == 'await' || lexeme == 'yield')) {
         _reportErrorForCurrentToken(
             ParserErrorCode.ASYNC_KEYWORD_USED_AS_IDENTIFIER);
       }
       return new SimpleIdentifier(getAndAdvance());
     }
     _reportErrorForCurrentToken(ParserErrorCode.MISSING_IDENTIFIER);
     return _createSyntheticIdentifier();
   }
 
   /**
-   * Parse a statement, starting with the given token.
-   *
-   * @param token the first token of the statement
-   * @return the statement that was parsed, or `null` if the tokens do not represent a
-   *         recognizable statement
+   * Parse a statement, starting with the given [token]. Return the statement
+   * that was parsed, or `null` if the tokens do not represent a recognizable
+   * statement.
    */
   Statement parseStatement(Token token) {
     _currentToken = token;
     return parseStatement2();
   }
 
   /**
-   * Parse a statement.
+   * Parse a statement. Return the statement that was parsed.
    *
-   * <pre>
-   * statement ::=
-   *     label* nonLabeledStatement
-   * </pre>
-   *
-   * @return the statement that was parsed
+   *     statement ::=
+   *         label* nonLabeledStatement
    */
   Statement parseStatement2() {
     List<Label> labels = new List<Label>();
     while (_matchesIdentifier() && _tokenMatches(_peek(), TokenType.COLON)) {
       labels.add(parseLabel());
     }
     Statement statement = _parseNonLabeledStatement();
     if (labels.isEmpty) {
       return statement;
     }
     return new LabeledStatement(labels, statement);
   }
 
   /**
-   * Parse a sequence of statements, starting with the given token.
-   *
-   * @param token the first token of the sequence of statement
-   * @return the statements that were parsed, or `null` if the tokens do not represent a
-   *         recognizable sequence of statements
+   * Parse a sequence of statements, starting with the given [token]. Return the
+   * statements that were parsed, or `null` if the tokens do not represent a
+   * recognizable sequence of statements.
    */
   List<Statement> parseStatements(Token token) {
     _currentToken = token;
     return _parseStatementList();
   }
 
   /**
-   * Parse a string literal.
+   * Parse a string literal. Return the string literal that was parsed.
    *
-   * <pre>
-   * stringLiteral ::=
-   *     MULTI_LINE_STRING+
-   *   | SINGLE_LINE_STRING+
-   * </pre>
-   *
-   * @return the string literal that was parsed
+   *     stringLiteral ::=
+   *         MULTI_LINE_STRING+
+   *       | SINGLE_LINE_STRING+
    */
   StringLiteral parseStringLiteral() {
     List<StringLiteral> strings = new List<StringLiteral>();
     while (_matches(TokenType.STRING)) {
       Token string = getAndAdvance();
       if (_matches(TokenType.STRING_INTERPOLATION_EXPRESSION) ||
           _matches(TokenType.STRING_INTERPOLATION_IDENTIFIER)) {
         strings.add(_parseStringInterpolation(string));
       } else {
         strings.add(new SimpleStringLiteral(
             string, _computeStringValue(string.lexeme, true, true)));
       }
     }
     if (strings.length < 1) {
       _reportErrorForCurrentToken(ParserErrorCode.EXPECTED_STRING_LITERAL);
       return _createSyntheticStringLiteral();
     } else if (strings.length == 1) {
       return strings[0];
     } else {
       return new AdjacentStrings(strings);
     }
   }
 
   /**
-   * Parse a list of type arguments.
+   * Parse a list of type arguments. Return the type argument list that was
+   * parsed.
    *
-   * <pre>
-   * typeArguments ::=
-   *     '<' typeList '>'
+   *     typeArguments ::=
+   *         '<' typeList '>'
    *
-   * typeList ::=
-   *     type (',' type)*
-   * </pre>
-   *
-   * @return the type argument list that was parsed
+   *     typeList ::=
+   *         type (',' type)*
    */
   TypeArgumentList parseTypeArgumentList() {
     Token leftBracket = _expect(TokenType.LT);
     List<TypeName> arguments = new List<TypeName>();
     arguments.add(parseTypeName());
     while (_optional(TokenType.COMMA)) {
       arguments.add(parseTypeName());
     }
     Token rightBracket = _expectGt();
     return new TypeArgumentList(leftBracket, arguments, rightBracket);
   }
 
   /**
-   * Parse a type name.
+   * Parse a type name. Return the type name that was parsed.
    *
-   * <pre>
-   * type ::=
-   *     qualified typeArguments?
-   * </pre>
-   *
-   * @return the type name that was parsed
+   *     type ::=
+   *         qualified typeArguments?
    */
   TypeName parseTypeName() {
     Identifier typeName;
     if (_matchesKeyword(Keyword.VAR)) {
       _reportErrorForCurrentToken(ParserErrorCode.VAR_AS_TYPE_NAME);
       typeName = new SimpleIdentifier(getAndAdvance());
     } else if (_matchesIdentifier()) {
       typeName = parsePrefixedIdentifier();
     } else {
       typeName = _createSyntheticIdentifier();
       _reportErrorForCurrentToken(ParserErrorCode.EXPECTED_TYPE_NAME);
     }
     TypeArgumentList typeArguments = null;
     if (_matches(TokenType.LT)) {
       typeArguments = parseTypeArgumentList();
     }
     return new TypeName(typeName, typeArguments);
   }
 
   /**
-   * Parse a type parameter.
+   * Parse a type parameter. Return the type parameter that was parsed.
    *
-   * <pre>
-   * typeParameter ::=
-   *     metadata name ('extends' bound)?
-   * </pre>
-   *
-   * @return the type parameter that was parsed
+   *     typeParameter ::=
+   *         metadata name ('extends' bound)?
    */
   TypeParameter parseTypeParameter() {
     CommentAndMetadata commentAndMetadata = _parseCommentAndMetadata();
     SimpleIdentifier name = parseSimpleIdentifier();
     if (_matchesKeyword(Keyword.EXTENDS)) {
       Token keyword = getAndAdvance();
       TypeName bound = parseTypeName();
       return new TypeParameter(commentAndMetadata.comment,
           commentAndMetadata.metadata, name, keyword, bound);
     }
     return new TypeParameter(commentAndMetadata.comment,
         commentAndMetadata.metadata, name, null, null);
   }
 
   /**
-   * Parse a list of type parameters.
+   * Parse a list of type parameters. Return the list of type parameters that
+   * were parsed.
    *
-   * <pre>
-   * typeParameterList ::=
-   *     '<' typeParameter (',' typeParameter)* '>'
-   * </pre>
-   *
-   * @return the list of type parameters that were parsed
+   *     typeParameterList ::=
+   *         '<' typeParameter (',' typeParameter)* '>'
    */
   TypeParameterList parseTypeParameterList() {
     Token leftBracket = _expect(TokenType.LT);
     List<TypeParameter> typeParameters = new List<TypeParameter>();
     typeParameters.add(parseTypeParameter());
     while (_optional(TokenType.COMMA)) {
       typeParameters.add(parseTypeParameter());
     }
     Token rightBracket = _expectGt();
     return new TypeParameterList(leftBracket, typeParameters, rightBracket);
   }
 
   /**
-   * Parse a with clause.
+   * Parse a with clause. Return the with clause that was parsed.
    *
-   * <pre>
-   * withClause ::=
-   *     'with' typeName (',' typeName)*
-   * </pre>
-   *
-   * @return the with clause that was parsed
+   *     withClause ::=
+   *         'with' typeName (',' typeName)*
    */
   WithClause parseWithClause() {
     Token with2 = _expectKeyword(Keyword.WITH);
     List<TypeName> types = new List<TypeName>();
     types.add(parseTypeName());
     while (_optional(TokenType.COMMA)) {
       types.add(parseTypeName());
     }
     return new WithClause(with2, types);
   }
 
   /**
    * Advance to the next token in the token stream.
    */
   void _advance() {
     _currentToken = _currentToken.next;
   }
 
   /**
-   * Append the character equivalent of the given scalar value to the given builder. Use the start
-   * and end indices to report an error, and don't append anything to the builder, if the scalar
-   * value is invalid.
-   *
-   * @param builder the builder to which the scalar value is to be appended
-   * @param escapeSequence the escape sequence that was parsed to produce the scalar value
-   * @param scalarValue the value to be appended
-   * @param startIndex the index of the first character representing the scalar value
-   * @param endIndex the index of the last character representing the scalar value
+   * Append the character equivalent of the given [scalarValue] to the given
+   * [builder]. Use the [startIndex] and [endIndex] to report an error, and
+   * don't append anything to the builder, if the scalar value is invalid. The
+   * [escapeSequence] is the escape sequence that was parsed to produce the
+   * scalar value (used for error reporting).
    */
   void _appendScalarValue(StringBuffer buffer, String escapeSequence,
       int scalarValue, int startIndex, int endIndex) {
     if (scalarValue < 0 ||
         scalarValue > Character.MAX_CODE_POINT ||
         (scalarValue >= 0xD800 && scalarValue <= 0xDFFF)) {
       _reportErrorForCurrentToken(
           ParserErrorCode.INVALID_CODE_POINT, [escapeSequence]);
       return;
     }
     if (scalarValue < Character.MAX_VALUE) {
       buffer.writeCharCode(scalarValue);
     } else {
       buffer.write(Character.toChars(scalarValue));
     }
   }
 
   /**
-   * Compute the content of a string with the given literal representation.
-   *
-   * @param lexeme the literal representation of the string
-   * @param first `true` if this is the first token in a string literal
-   * @param last `true` if this is the last token in a string literal
-   * @return the actual value of the string
+   * Return the content of a string with the given literal representation. The
+   * [lexeme] is the literal representation of the string. The flag [first] is
+   * `true` if this is the first token in a string literal. The flag [last] is
+   * `true` if this is the last token in a string literal.
    */
   String _computeStringValue(String lexeme, bool first, bool last) {
     bool isRaw = false;
     int start = 0;
     if (first) {
       if (StringUtilities.startsWith4(lexeme, 0, 0x72, 0x22, 0x22, 0x22) ||
           StringUtilities.startsWith4(lexeme, 0, 0x72, 0x27, 0x27, 0x27)) {
         isRaw = true;
         start += 4;
       } else if (StringUtilities.startsWith2(lexeme, 0, 0x72, 0x22) ||
@@ skipping 28 matching lines @@
     }
     StringBuffer buffer = new StringBuffer();
     int index = start;
     while (index < end) {
       index = _translateCharacter(buffer, lexeme, index);
     }
     return buffer.toString();
   }
 
   /**
-   * Convert the given method declaration into the nearest valid top-level function declaration.
-   *
-   * @param method the method to be converted
-   * @return the function declaration that most closely captures the components of the given method
-   *         declaration
+   * Convert the given [method] declaration into the nearest valid top-level
+   * function declaration (that is, the function declaration that most closely
+   * captures the components of the given method declaration).
    */
   FunctionDeclaration _convertToFunctionDeclaration(MethodDeclaration method) =>
       new FunctionDeclaration(method.documentationComment, method.metadata,
           method.externalKeyword, method.returnType, method.propertyKeyword,
           method.name, new FunctionExpression(method.parameters, method.body));
 
   /**
-   * Return `true` if the current token could be the start of a compilation unit member. This
-   * method is used for recovery purposes to decide when to stop skipping tokens after finding an
-   * error while parsing a compilation unit member.
-   *
-   * @return `true` if the current token could be the start of a compilation unit member
+   * Return `true` if the current token could be the start of a compilation unit
+   * member. This method is used for recovery purposes to decide when to stop
+   * skipping tokens after finding an error while parsing a compilation unit
+   * member.
    */
   bool _couldBeStartOfCompilationUnitMember() {
     if ((_matchesKeyword(Keyword.IMPORT) ||
             _matchesKeyword(Keyword.EXPORT) ||
             _matchesKeyword(Keyword.LIBRARY) ||
             _matchesKeyword(Keyword.PART)) &&
         !_tokenMatches(_peek(), TokenType.PERIOD) &&
         !_tokenMatches(_peek(), TokenType.LT)) {
       // This looks like the start of a directive
       return true;
@@ skipping 24 matching lines @@
           _matchesKeyword(Keyword.SET) ||
           (_matchesKeyword(Keyword.OPERATOR) && _isOperator(_peek())) ||
           _matchesIdentifier()) {
         return true;
       }
     }
     return false;
   }
 
   /**
-   * Create a synthetic identifier.
-   *
-   * @return the synthetic identifier that was created
+   * Return a synthetic identifier.
    */
   SimpleIdentifier _createSyntheticIdentifier() {
     Token syntheticToken;
     if (_currentToken.type == TokenType.KEYWORD) {
       // Consider current keyword token as an identifier.
       // It is not always true, e.g. "^is T" where "^" is place the place for
       // synthetic identifier. By creating SyntheticStringToken we can
       // distinguish a real identifier from synthetic. In the code completion
       // behavior will depend on a cursor position - before or on "is".
       syntheticToken = _injectToken(new SyntheticStringToken(
           TokenType.IDENTIFIER, _currentToken.lexeme, _currentToken.offset));
     } else {
       syntheticToken = _createSyntheticToken(TokenType.IDENTIFIER);
     }
     return new SimpleIdentifier(syntheticToken);
   }
 
   /**
-   * Create a synthetic token representing the given keyword.
-   *
-   * @return the synthetic token that was created
+   * Return a synthetic token representing the given [keyword].
    */
   Token _createSyntheticKeyword(Keyword keyword) => _injectToken(
       new Parser_SyntheticKeywordToken(keyword, _currentToken.offset));
 
   /**
-   * Create a synthetic string literal.
-   *
-   * @return the synthetic string literal that was created
+   * Return a synthetic string literal.
    */
   SimpleStringLiteral _createSyntheticStringLiteral() =>
       new SimpleStringLiteral(_createSyntheticToken(TokenType.STRING), "");
 
   /**
-   * Create a synthetic token with the given type.
-   *
-   * @return the synthetic token that was created
+   * Return a synthetic token with the given [type].
    */
   Token _createSyntheticToken(TokenType type) =>
       _injectToken(new StringToken(type, "", _currentToken.offset));
 
   /**
    * Create and return a new token with the given [type]. The token will replace
    * the first portion of the given [token], so it will have the same offset and
    * will have any comments that might have preceeded the token.
    */
   Token _createToken(Token token, TokenType type, {bool isBegin: false}) {
     CommentToken comments = token.precedingComments;
     if (comments == null) {
       if (isBegin) {
         return new BeginToken(type, token.offset);
       }
       return new Token(type, token.offset);
     } else if (isBegin) {
       return new BeginTokenWithComment(type, token.offset, comments);
     }
     return new TokenWithComment(type, token.offset, comments);
   }
 
   /**
-   * Check that the given expression is assignable and report an error if it isn't.
+   * Check that the given [expression] is assignable and report an error if it
+   * isn't.
    *
-   * <pre>
-   * assignableExpression ::=
-   *     primary (arguments* assignableSelector)+
-   *   | 'super' assignableSelector
-   *   | identifier
+   *     assignableExpression ::=
+   *         primary (arguments* assignableSelector)+
+   *       | 'super' assignableSelector
+   *       | identifier
    *
-   * assignableSelector ::=
-   *     '[' expression ']'
-   *   | '.' identifier
-   * </pre>
-   *
-   * @param expression the expression being checked
+   *     assignableSelector ::=
+   *         '[' expression ']'
+   *       | '.' identifier
    */
   void _ensureAssignable(Expression expression) {
     if (expression != null && !expression.isAssignable) {
       _reportErrorForCurrentToken(
           ParserErrorCode.ILLEGAL_ASSIGNMENT_TO_NON_ASSIGNABLE);
     }
   }
 
   /**
    * If the current token has the expected type, return it after advancing to
@@ skipping 21 matching lines @@
       _reportErrorForToken(ParserErrorCode.EXPECTED_TOKEN,
           _currentToken.previous, [type.lexeme]);
     } else {
       _reportErrorForCurrentToken(
           ParserErrorCode.EXPECTED_TOKEN, [type.lexeme]);
     }
     return _currentToken;
   }
 
   /**
-   * If the current token has the type [TokenType.GT], return it after advancing to the next
-   * token. Otherwise report an error and return the current token without advancing.
-   *
-   * @return the token that matched the given type
+   * If the current token has the type [TokenType.GT], return it after advancing
+   * to the next token. Otherwise report an error and return the current token
+   * without advancing.
    */
   Token _expectGt() {
     if (_matchesGt()) {
       return getAndAdvance();
     }
     _reportErrorForCurrentToken(
         ParserErrorCode.EXPECTED_TOKEN, [TokenType.GT.lexeme]);
     return _currentToken;
   }
 
   /**
-   * If the current token is a keyword matching the given string, return it after advancing to the
-   * next token. Otherwise report an error and return the current token without advancing.
-   *
-   * @param keyword the keyword that is expected
-   * @return the token that matched the given type
+   * If the current token is a keyword matching the given [keyword], return it
+   * after advancing to the next token. Otherwise report an error and return the
+   * current token without advancing.
    */
   Token _expectKeyword(Keyword keyword) {
     if (_matchesKeyword(keyword)) {
       return getAndAdvance();
     }
     // Remove uses of this method in favor of matches?
     // Pass in the error code to use to report the error?
     _reportErrorForCurrentToken(
         ParserErrorCode.EXPECTED_TOKEN, [keyword.syntax]);
     return _currentToken;
   }
 
   /**
-   * If [currentToken] is a semicolon, returns it; otherwise reports error and creates a
-   * synthetic one.
-   *
-   * TODO(scheglov) consider pushing this into [expect]
+   * If the current token is a semicolon, return it after advancing to the next
+   * token. Otherwise report an error and create a synthetic semicolon.
    */
   Token _expectSemicolon() {
+    // TODO(scheglov) consider pushing this behavior into [_expect]
     if (_matches(TokenType.SEMICOLON)) {
       return getAndAdvance();
     } else {
       _reportErrorForToken(
           ParserErrorCode.EXPECTED_TOKEN, _currentToken.previous, [";"]);
       return _createSyntheticToken(TokenType.SEMICOLON);
     }
   }
 
   /**
-   * Search the given list of ranges for a range that contains the given index. Return the range
-   * that was found, or `null` if none of the ranges contain the index.
-   *
-   * @param ranges the ranges to be searched
-   * @param index the index contained in the returned range
-   * @return the range that was found
+   * Search the given list of [ranges] for a range that contains the given
+   * [index]. Return the range that was found, or `null` if none of the ranges
+   * contain the index.
    */
   List<int> _findRange(List<List<int>> ranges, int index) {
     int rangeCount = ranges.length;
     for (int i = 0; i < rangeCount; i++) {
       List<int> range = ranges[i];
       if (range[0] <= index && index <= range[1]) {
         return range;
       } else if (index < range[0]) {
         return null;
       }
     }
     return null;
   }
 
   /**
-   * Return a list of the ranges of characters in the given comment string that should be treated as
-   * code blocks.
-   *
-   * @param comment the comment being processed
-   * @return the ranges of characters that should be treated as code blocks
+   * Return a list of the ranges of characters in the given [comment] that
+   * should be treated as code blocks.
    */
   List<List<int>> _getCodeBlockRanges(String comment) {
     List<List<int>> ranges = new List<List<int>>();
     int length = comment.length;
     if (length < 3) {
       return ranges;
     }
     int index = 0;
     int firstChar = comment.codeUnitAt(0);
     if (firstChar == 0x2F) {
@@ skipping 33 matching lines @@
         ranges.add(<int>[index, end]);
         index = end + 1;
       } else {
         index = index + 1;
       }
     }
     return ranges;
   }
 
   /**
-   * Return the end token associated with the given begin token, or `null` if either the given
-   * token is not a begin token or it does not have an end token associated with it.
-   *
-   * @param beginToken the token that is expected to have an end token associated with it
-   * @return the end token associated with the begin token
+   * Return the end token associated with the given [beginToken], or `null` if
+   * either the given token is not a begin token or it does not have an end
+   * token associated with it.
    */
   Token _getEndToken(Token beginToken) {
     if (beginToken is BeginToken) {
       return beginToken.endToken;
     }
     return null;
   }
 
   /**
-   * Inject the given token into the token stream immediately before the current token.
-   *
-   * @param token the token to be added to the token stream
-   * @return the token that was just added to the token stream
+   * Inject the given [token] into the token stream immediately before the
+   * current token.
    */
   Token _injectToken(Token token) {
     Token previous = _currentToken.previous;
     token.setNext(_currentToken);
     previous.setNext(token);
     return token;
   }
 
   /**
    * Return `true` if the current token appears to be the beginning of a
@@ skipping 35 matching lines @@
       if (afterName == null) {
         return false;
       }
       return _tokenMatches(afterName, TokenType.FUNCTION) ||
           _tokenMatches(afterName, TokenType.OPEN_CURLY_BRACKET);
     }
     return false;
   }
 
   /**
-   * Return `true` if the given token appears to be the beginning of a function expression.
-   *
-   * @param startToken the token that might be the start of a function expression
-   * @return `true` if the given token appears to be the beginning of a function expression
+   * Return `true` if the given [token] appears to be the beginning of a
+   * function expression.
    */
-  bool _isFunctionExpression(Token startToken) {
+  bool _isFunctionExpression(Token token) {
     // Function expressions aren't allowed in initializer lists.
     if (_inInitializer) {
       return false;
     }
-    Token afterParameters = _skipFormalParameterList(startToken);
+    Token afterParameters = _skipFormalParameterList(token);
     if (afterParameters == null) {
       return false;
     }
     if (afterParameters
         .matchesAny([TokenType.OPEN_CURLY_BRACKET, TokenType.FUNCTION])) {
       return true;
     }
     String lexeme = afterParameters.lexeme;
     return lexeme == ASYNC || lexeme == SYNC;
   }
 
   /**
-   * Return `true` if the given character is a valid hexadecimal digit.
-   *
-   * @param character the character being tested
-   * @return `true` if the character is a valid hexadecimal digit
+   * Return `true` if the given [character] is a valid hexadecimal digit.
    */
   bool _isHexDigit(int character) => (0x30 <= character && character <= 0x39) ||
       (0x41 <= character && character <= 0x46) ||
       (0x61 <= character && character <= 0x66);
 
   /**
-   * Return `true` if the current token is the first token in an initialized variable
-   * declaration rather than an expression. This method assumes that we have already skipped past
-   * any metadata that might be associated with the declaration.
+   * Return `true` if the current token is the first token in an initialized
+   * variable declaration rather than an expression. This method assumes that we
+   * have already skipped past any metadata that might be associated with the
+   * declaration.
    *
-   * <pre>
-   * initializedVariableDeclaration ::=
-   *     declaredIdentifier ('=' expression)? (',' initializedIdentifier)*
+   *     initializedVariableDeclaration ::=
+   *         declaredIdentifier ('=' expression)? (',' initializedIdentifier)*
    *
-   * declaredIdentifier ::=
-   *     metadata finalConstVarOrType identifier
+   *     declaredIdentifier ::=
+   *         metadata finalConstVarOrType identifier
    *
-   * finalConstVarOrType ::=
-   *     'final' type?
-   *   | 'const' type?
-   *   | 'var'
-   *   | type
+   *     finalConstVarOrType ::=
+   *         'final' type?
+   *       | 'const' type?
+   *       | 'var'
+   *       | type
    *
-   * type ::=
-   *     qualified typeArguments?
+   *     type ::=
+   *         qualified typeArguments?
    *
-   * initializedIdentifier ::=
-   *     identifier ('=' expression)?
-   * </pre>
-   *
-   * @return `true` if the current token is the first token in an initialized variable
-   *         declaration
+   *     initializedIdentifier ::=
+   *         identifier ('=' expression)?
    */
   bool _isInitializedVariableDeclaration() {
     if (_matchesKeyword(Keyword.FINAL) || _matchesKeyword(Keyword.VAR)) {
       // An expression cannot start with a keyword other than 'const',
       // 'rethrow', or 'throw'.
       return true;
     }
     if (_matchesKeyword(Keyword.CONST)) {
       // Look to see whether we might be at the start of a list or map literal,
       // otherwise this should be the start of a variable declaration.
@@ skipping 16 matching lines @@
       return false;
     }
     TokenType type = token.type;
     return type == TokenType.EQ ||
         type == TokenType.COMMA ||
         type == TokenType.SEMICOLON ||
         _tokenMatchesKeyword(token, Keyword.IN);
   }
 
   /**
-   * Given that we have just found bracketed text within a comment, look to see whether that text is
-   * (a) followed by a parenthesized link address, (b) followed by a colon, or (c) followed by
-   * optional whitespace and another square bracket.
+   * Given that we have just found bracketed text within the given [comment],
+   * look to see whether that text is (a) followed by a parenthesized link
+   * address, (b) followed by a colon, or (c) followed by optional whitespace
+   * and another square bracket. The [rightIndex] is the index of the right
+   * bracket. Return `true` if the bracketed text is followed by a link address.
    *
-   * This method uses the syntax described by the <a
-   * href="http://daringfireball.net/projects/markdown/syntax">markdown</a> project.
-   *
-   * @param comment the comment text in which the bracketed text was found
-   * @param rightIndex the index of the right bracket
-   * @return `true` if the bracketed text is followed by a link address
+   * This method uses the syntax described by the
+   * <a href="http://daringfireball.net/projects/markdown/syntax">markdown</a>
+   * project.
    */
   bool _isLinkText(String comment, int rightIndex) {
     int length = comment.length;
     int index = rightIndex + 1;
     if (index >= length) {
       return false;
     }
     int nextChar = comment.codeUnitAt(index);
     if (nextChar == 0x28 || nextChar == 0x3A) {
       return true;
     }
     while (Character.isWhitespace(nextChar)) {
       index = index + 1;
       if (index >= length) {
         return false;
       }
       nextChar = comment.codeUnitAt(index);
     }
     return nextChar == 0x5B;
   }
 
   /**
-   * Return `true` if the given token appears to be the beginning of an operator declaration.
-   *
-   * @param startToken the token that might be the start of an operator declaration
-   * @return `true` if the given token appears to be the beginning of an operator declaration
+   * Return `true` if the given [startToken] appears to be the beginning of an
+   * operator declaration.
    */
   bool _isOperator(Token startToken) {
     // Accept any operator here, even if it is not user definable.
     if (!startToken.isOperator) {
       return false;
     }
     // Token "=" means that it is actually field initializer.
     if (startToken.type == TokenType.EQ) {
       return false;
     }
     // Consume all operator tokens.
     Token token = startToken.next;
     while (token.isOperator) {
       token = token.next;
     }
     // Formal parameter list is expect now.
     return _tokenMatches(token, TokenType.OPEN_PAREN);
   }
 
   /**
-   * Return `true` if the current token appears to be the beginning of a switch member.
-   *
-   * @return `true` if the current token appears to be the beginning of a switch member
+   * Return `true` if the current token appears to be the beginning of a switch
+   * member.
    */
   bool _isSwitchMember() {
     Token token = _currentToken;
     while (_tokenMatches(token, TokenType.IDENTIFIER) &&
         _tokenMatches(token.next, TokenType.COLON)) {
       token = token.next.next;
     }
     if (token.type == TokenType.KEYWORD) {
       Keyword keyword = (token as KeywordToken).keyword;
       return keyword == Keyword.CASE || keyword == Keyword.DEFAULT;
@@ skipping 29 matching lines @@
 
   /**
    * Increments the error reporting lock level. If level is more than `0`, then
    * [reportError] wont report any error.
    */
   void _lockErrorListener() {
     _errorListenerLock++;
   }
 
   /**
-   * Return `true` if the current token has the given type. Note that the method
-   * [_matchesGt] should be used if the argument to this method would be
+   * Return `true` if the current token has the given [type]. Note that the
+   * method [_matchesGt] should be used if the argument to this method would be
    * [TokenType.GT].
-   *
-   * @param type the type of token that can optionally appear in the current location
-   * @return `true` if the current token has the given type
    */
   bool _matches(TokenType type) => _currentToken.type == type;
 
   /**
-   * Return `true` if the current token has a type of [TokenType.GT]. Note that this
-   * method, unlike other variants, will modify the token stream if possible to match desired type.
-   * In particular, if the next token is either a '>>' or '>>>', the token stream will be re-written
-   * and `true` will be returned.
-   *
-   * @return `true` if the current token has a type of [TokenType.GT]
+   * Return `true` if the current token has a type of [TokenType.GT]. Note that
+   * this method, unlike other variants, will modify the token stream if
+   * possible to match desired type. In particular, if the next token is either
+   * a '>>' or '>>>', the token stream will be re-written and `true` will be
+   * returned.
    */
   bool _matchesGt() {
     TokenType currentType = _currentToken.type;
     if (currentType == TokenType.GT) {
       return true;
     } else if (currentType == TokenType.GT_GT) {
       Token first = _createToken(_currentToken, TokenType.GT);
       Token second = new Token(TokenType.GT, _currentToken.offset + 1);
       second.setNext(_currentToken.next);
       first.setNext(second);
@@ skipping 17 matching lines @@
       second.setNext(third);
       first.setNext(second);
       _currentToken.previous.setNext(first);
       _currentToken = first;
       return true;
     }
     return false;
   }
 
   /**
-   * Return `true` if the current token is a valid identifier. Valid identifiers include
-   * built-in identifiers (pseudo-keywords).
-   *
-   * @return `true` if the current token is a valid identifier
+   * Return `true` if the current token is a valid identifier. Valid identifiers
+   * include built-in identifiers (pseudo-keywords).
    */
   bool _matchesIdentifier() => _tokenMatchesIdentifier(_currentToken);
 
   /**
-   * Return `true` if the current token matches the given keyword.
-   *
-   * @param keyword the keyword that can optionally appear in the current location
-   * @return `true` if the current token matches the given keyword
+   * Return `true` if the current token matches the given [keyword].
    */
   bool _matchesKeyword(Keyword keyword) =>
       _tokenMatchesKeyword(_currentToken, keyword);
 
   /**
-   * Return `true` if the current token matches the given identifier.
-   *
-   * @param identifier the identifier that can optionally appear in the current location
-   * @return `true` if the current token matches the given identifier
+   * Return `true` if the current token matches the given [identifier].
    */
   bool _matchesString(String identifier) =>
       _currentToken.type == TokenType.IDENTIFIER &&
           _currentToken.lexeme == identifier;
 
   /**
-   * If the current token has the given type, then advance to the next token and return `true`
-   * . Otherwise, return `false` without advancing. This method should not be invoked with an
-   * argument value of [TokenType.GT].
-   *
-   * @param type the type of token that can optionally appear in the current location
-   * @return `true` if the current token has the given type
+   * If the current token has the given [type], then advance to the next token
+   * and return `true`. Otherwise, return `false` without advancing. This method
+   * should not be invoked with an argument value of [TokenType.GT].
    */
   bool _optional(TokenType type) {
     if (_matches(type)) {
       _advance();
       return true;
     }
     return false;
   }
 
   /**
-   * Parse an additive expression.
+   * Parse an additive expression. Return the additive expression that was
+   * parsed.
    *
-   * <pre>
-   * additiveExpression ::=
-   *     multiplicativeExpression (additiveOperator multiplicativeExpression)*
-   *   | 'super' (additiveOperator multiplicativeExpression)+
-   * </pre>
-   *
-   * @return the additive expression that was parsed
+   *     additiveExpression ::=
+   *         multiplicativeExpression (additiveOperator multiplicativeExpression)*
+   *       | 'super' (additiveOperator multiplicativeExpression)+
    */
   Expression _parseAdditiveExpression() {
     Expression expression;
     if (_matchesKeyword(Keyword.SUPER) &&
         _currentToken.next.type.isAdditiveOperator) {
       expression = new SuperExpression(getAndAdvance());
     } else {
       expression = _parseMultiplicativeExpression();
     }
     while (_currentToken.type.isAdditiveOperator) {
       Token operator = getAndAdvance();
       expression = new BinaryExpression(
           expression, operator, _parseMultiplicativeExpression());
     }
     return expression;
   }
 
   /**
-   * Parse an assert statement.
+   * Parse an assert statement. Return the assert statement.
    *
-   * <pre>
-   * assertStatement ::=
-   *     'assert' '(' conditionalExpression ')' ';'
-   * </pre>
-   *
-   * @return the assert statement
+   *     assertStatement ::=
+   *         'assert' '(' conditionalExpression ')' ';'
    */
   AssertStatement _parseAssertStatement() {
     Token keyword = _expectKeyword(Keyword.ASSERT);
     Token leftParen = _expect(TokenType.OPEN_PAREN);
     Expression expression = parseExpression2();
     if (expression is AssignmentExpression) {
       _reportErrorForNode(
           ParserErrorCode.ASSERT_DOES_NOT_TAKE_ASSIGNMENT, expression);
     } else if (expression is CascadeExpression) {
       _reportErrorForNode(
           ParserErrorCode.ASSERT_DOES_NOT_TAKE_CASCADE, expression);
     } else if (expression is ThrowExpression) {
       _reportErrorForNode(
           ParserErrorCode.ASSERT_DOES_NOT_TAKE_THROW, expression);
     } else if (expression is RethrowExpression) {
       _reportErrorForNode(
           ParserErrorCode.ASSERT_DOES_NOT_TAKE_RETHROW, expression);
     }
     Token rightParen = _expect(TokenType.CLOSE_PAREN);
     Token semicolon = _expect(TokenType.SEMICOLON);
     return new AssertStatement(
         keyword, leftParen, expression, rightParen, semicolon);
   }
 
   /**
-   * Parse an assignable expression.
+   * Parse an assignable expression. The [primaryAllowed] is `true` if the
+   * expression is allowed to be a primary without any assignable selector.
+   * Return the assignable expression that was parsed.
    *
-   * <pre>
-   * assignableExpression ::=
-   *     primary (arguments* assignableSelector)+
-   *   | 'super' assignableSelector
-   *   | identifier
-   * </pre>
-   *
-   * @param primaryAllowed `true` if the expression is allowed to be a primary without any
-   *          assignable selector
-   * @return the assignable expression that was parsed
+   *     assignableExpression ::=
+   *         primary (arguments* assignableSelector)+
+   *       | 'super' assignableSelector
+   *       | identifier
    */
   Expression _parseAssignableExpression(bool primaryAllowed) {
     if (_matchesKeyword(Keyword.SUPER)) {
       return _parseAssignableSelector(
           new SuperExpression(getAndAdvance()), false);
     }
     //
     // A primary expression can start with an identifier. We resolve the
     // ambiguity by determining whether the primary consists of anything other
     // than an identifier and/or is followed by an assignableSelector.
@@ skipping 31 matching lines @@
               identifier.prefix, identifier.period, identifier.identifier);
         }
         return expression;
       }
       expression = selectorExpression;
       isOptional = true;
     }
   }
 
   /**
-   * Parse an assignable selector.
+   * Parse an assignable selector. The [prefix] is the expression preceding the
+   * selector. The [optional] is `true` if the selector is optional. Return the
+   * assignable selector that was parsed, or the original prefix if there was no
+   * assignable selector.
    *
-   * <pre>
-   * assignableSelector ::=
-   *     '[' expression ']'
-   *   | '.' identifier
-   * </pre>
-   *
-   * @param prefix the expression preceding the selector
-   * @param optional `true` if the selector is optional
-   * @return the assignable selector that was parsed, or the original prefix if there was no
-   *         assignable selector
+   *     assignableSelector ::=
+   *         '[' expression ']'
+   *       | '.' identifier
    */
   Expression _parseAssignableSelector(Expression prefix, bool optional) {
     if (_matches(TokenType.OPEN_SQUARE_BRACKET)) {
       Token leftBracket = getAndAdvance();
       bool wasInInitializer = _inInitializer;
       _inInitializer = false;
       try {
         Expression index = parseExpression2();
         Token rightBracket = _expect(TokenType.CLOSE_SQUARE_BRACKET);
         return new IndexExpression.forTarget(
             prefix, leftBracket, index, rightBracket);
       } finally {
         _inInitializer = wasInInitializer;
       }
     } else if (_matches(TokenType.PERIOD)) {
       Token period = getAndAdvance();
       return new PropertyAccess(prefix, period, parseSimpleIdentifier());
     } else {
       if (!optional) {
         // Report the missing selector.
         _reportErrorForCurrentToken(
             ParserErrorCode.MISSING_ASSIGNABLE_SELECTOR);
       }
       return prefix;
     }
   }
 
   /**
-   * Parse a await expression.
+   * Parse a await expression. Return the await expression that was parsed.
    *
-   * <pre>
-   * awaitExpression ::=
-   *     'await' unaryExpression
-   * </pre>
-   *
-   * @return the await expression that was parsed
+   *     awaitExpression ::=
+   *         'await' unaryExpression
    */
   AwaitExpression _parseAwaitExpression() {
     Token awaitToken = getAndAdvance();
     Expression expression = _parseUnaryExpression();
     return new AwaitExpression(awaitToken, expression);
   }
 
   /**
-   * Parse a bitwise and expression.
+   * Parse a bitwise and expression. Return the bitwise and expression that was
+   * parsed.
    *
-   * <pre>
-   * bitwiseAndExpression ::=
-   *     shiftExpression ('&' shiftExpression)*
-   *   | 'super' ('&' shiftExpression)+
-   * </pre>
-   *
-   * @return the bitwise and expression that was parsed
+   *     bitwiseAndExpression ::=
+   *         shiftExpression ('&' shiftExpression)*
+   *       | 'super' ('&' shiftExpression)+
    */
   Expression _parseBitwiseAndExpression() {
     Expression expression;
     if (_matchesKeyword(Keyword.SUPER) &&
         _tokenMatches(_peek(), TokenType.AMPERSAND)) {
       expression = new SuperExpression(getAndAdvance());
     } else {
       expression = _parseShiftExpression();
     }
     while (_matches(TokenType.AMPERSAND)) {
       Token operator = getAndAdvance();
       expression =
           new BinaryExpression(expression, operator, _parseShiftExpression());
     }
     return expression;
   }
 
   /**
-   * Parse a bitwise exclusive-or expression.
+   * Parse a bitwise exclusive-or expression. Return the bitwise exclusive-or
+   * expression that was parsed.
    *
-   * <pre>
-   * bitwiseXorExpression ::=
-   *     bitwiseAndExpression ('^' bitwiseAndExpression)*
-   *   | 'super' ('^' bitwiseAndExpression)+
-   * </pre>
-   *
-   * @return the bitwise exclusive-or expression that was parsed
+   *     bitwiseXorExpression ::=
+   *         bitwiseAndExpression ('^' bitwiseAndExpression)*
+   *       | 'super' ('^' bitwiseAndExpression)+
    */
   Expression _parseBitwiseXorExpression() {
     Expression expression;
     if (_matchesKeyword(Keyword.SUPER) &&
         _tokenMatches(_peek(), TokenType.CARET)) {
       expression = new SuperExpression(getAndAdvance());
     } else {
       expression = _parseBitwiseAndExpression();
     }
     while (_matches(TokenType.CARET)) {
       Token operator = getAndAdvance();
       expression = new BinaryExpression(
           expression, operator, _parseBitwiseAndExpression());
     }
     return expression;
   }
 
   /**
-   * Parse a break statement.
+   * Parse a break statement. Return the break statement that was parsed.
    *
-   * <pre>
-   * breakStatement ::=
-   *     'break' identifier? ';'
-   * </pre>
-   *
-   * @return the break statement that was parsed
+   *     breakStatement ::=
+   *         'break' identifier? ';'
    */
   Statement _parseBreakStatement() {
     Token breakKeyword = _expectKeyword(Keyword.BREAK);
     SimpleIdentifier label = null;
     if (_matchesIdentifier()) {
       label = parseSimpleIdentifier();
     }
     if (!_inLoop && !_inSwitch && label == null) {
       _reportErrorForToken(ParserErrorCode.BREAK_OUTSIDE_OF_LOOP, breakKeyword);
     }
     Token semicolon = _expect(TokenType.SEMICOLON);
     return new BreakStatement(breakKeyword, label, semicolon);
   }
 
   /**
-   * Parse a cascade section.
+   * Parse a cascade section. Return the expression representing the cascaded
+   * method invocation.
    *
-   * <pre>
-   * cascadeSection ::=
-   *     '..' (cascadeSelector arguments*) (assignableSelector arguments*)* cascadeAssignment?
+   *     cascadeSection ::=
+   *         '..' (cascadeSelector arguments*) (assignableSelector arguments*)* cascadeAssignment?
    *
-   * cascadeSelector ::=
-   *     '[' expression ']'
-   *   | identifier
+   *     cascadeSelector ::=
+   *         '[' expression ']'
+   *       | identifier
    *
-   * cascadeAssignment ::=
-   *     assignmentOperator expressionWithoutCascade
-   * </pre>
-   *
-   * @return the expression representing the cascaded method invocation
+   *     cascadeAssignment ::=
+   *         assignmentOperator expressionWithoutCascade
    */
   Expression _parseCascadeSection() {
     Token period = _expect(TokenType.PERIOD_PERIOD);
     Expression expression = null;
     SimpleIdentifier functionName = null;
     if (_matchesIdentifier()) {
       functionName = parseSimpleIdentifier();
     } else if (_currentToken.type == TokenType.OPEN_SQUARE_BRACKET) {
       Token leftBracket = getAndAdvance();
       bool wasInInitializer = _inInitializer;
@@ skipping 59 matching lines @@
     if (_currentToken.type.isAssignmentOperator) {
       Token operator = getAndAdvance();
       _ensureAssignable(expression);
       expression = new AssignmentExpression(
           expression, operator, parseExpressionWithoutCascade());
     }
     return expression;
   }
 
   /**
-   * Parse a class declaration.
+   * Parse a class declaration. The [commentAndMetadata] is the metadata to be
+   * associated with the member. The [abstractKeyword] is the token for the
+   * keyword 'abstract', or `null` if the keyword was not given. Return the
+   * class declaration that was parsed.
    *
-   * <pre>
-   * classDeclaration ::=
-   *     metadata 'abstract'? 'class' name typeParameterList? (extendsClause withClause?)? implementsClause? '{' classMembers '}' |
-   *     metadata 'abstract'? 'class' mixinApplicationClass
-   * </pre>
-   *
-   * @param commentAndMetadata the metadata to be associated with the member
-   * @param abstractKeyword the token for the keyword 'abstract', or `null` if the keyword was
-   *          not given
-   * @return the class declaration that was parsed
+   *     classDeclaration ::=
+   *         metadata 'abstract'? 'class' name typeParameterList? (extendsClause withClause?)? implementsClause? '{' classMembers '}' |
+   *         metadata 'abstract'? 'class' mixinApplicationClass
    */
   CompilationUnitMember _parseClassDeclaration(
       CommentAndMetadata commentAndMetadata, Token abstractKeyword) {
     Token keyword = _expectKeyword(Keyword.CLASS);
     if (_matchesIdentifier()) {
       Token next = _peek();
       if (_tokenMatches(next, TokenType.LT)) {
         next = _skipTypeParameterList(next);
         if (next != null && _tokenMatches(next, TokenType.EQ)) {
           return _parseClassTypeAlias(
@@ skipping 91 matching lines @@
     }
     ClassDeclaration classDeclaration = new ClassDeclaration(
         commentAndMetadata.comment, commentAndMetadata.metadata,
         abstractKeyword, keyword, name, typeParameters, extendsClause,
         withClause, implementsClause, leftBracket, members, rightBracket);
     classDeclaration.nativeClause = nativeClause;
     return classDeclaration;
   }
 
   /**
-   * Parse a list of class members.
+   * Parse a list of class members. The [className] is the name of the class
+   * whose members are being parsed. The [closingBracket] is the closing bracket
+   * for the class, or `null` if the closing bracket is missing. Return the list
+   * of class members that were parsed.
    *
-   * <pre>
-   * classMembers ::=
-   *     (metadata memberDefinition)*
-   * </pre>
-   *
-   * @param className the name of the class whose members are being parsed
-   * @param closingBracket the closing bracket for the class, or `null` if the closing bracket
-   *          is missing
-   * @return the list of class members that were parsed
+   *     classMembers ::=
+   *         (metadata memberDefinition)*
    */
   List<ClassMember> _parseClassMembers(String className, Token closingBracket) {
     List<ClassMember> members = new List<ClassMember>();
     Token memberStart = _currentToken;
     while (!_matches(TokenType.EOF) &&
         !_matches(TokenType.CLOSE_CURLY_BRACKET) &&
         (closingBracket != null ||
             (!_matchesKeyword(Keyword.CLASS) &&
                 !_matchesKeyword(Keyword.TYPEDEF)))) {
       if (_matches(TokenType.SEMICOLON)) {
@@ skipping 12 matching lines @@
           _currentToken.lexeme
         ]);
         _advance();
       }
       memberStart = _currentToken;
     }
     return members;
   }
 
   /**
-   * Parse a class type alias.
+   * Parse a class type alias. The [commentAndMetadata] is the metadata to be
+   * associated with the member. The [abstractKeyword] is the token representing
+   * the 'abstract' keyword. The [classKeyword] is the token representing the
+   * 'class' keyword. Return the class type alias that was parsed.
    *
-   * <pre>
-   * classTypeAlias ::=
-   *     identifier typeParameters? '=' 'abstract'? mixinApplication
+   *     classTypeAlias ::=
+   *         identifier typeParameters? '=' 'abstract'? mixinApplication
    *
-   * mixinApplication ::=
-   *     type withClause implementsClause? ';'
-   * </pre>
-   *
-   * @param commentAndMetadata the metadata to be associated with the member
-   * @param abstractKeyword the token representing the 'abstract' keyword
-   * @param classKeyword the token representing the 'class' keyword
-   * @return the class type alias that was parsed
+   *     mixinApplication ::=
+   *         type withClause implementsClause? ';'
    */
   ClassTypeAlias _parseClassTypeAlias(CommentAndMetadata commentAndMetadata,
       Token abstractKeyword, Token classKeyword) {
     SimpleIdentifier className = parseSimpleIdentifier();
     TypeParameterList typeParameters = null;
     if (_matches(TokenType.LT)) {
       typeParameters = parseTypeParameterList();
     }
     Token equals = _expect(TokenType.EQ);
     TypeName superclass = parseTypeName();
@@ skipping 24 matching lines @@
       }
       semicolon = _createSyntheticToken(TokenType.SEMICOLON);
     }
     return new ClassTypeAlias(commentAndMetadata.comment,
         commentAndMetadata.metadata, classKeyword, className, typeParameters,
         equals, abstractKeyword, superclass, withClause, implementsClause,
         semicolon);
   }
 
   /**
-   * Parse a list of combinators in a directive.
+   * Parse a list of combinators in a directive. Return the combinators that
+   * were parsed.
    *
-   * <pre>
-   * combinator ::=
-   *     'show' identifier (',' identifier)*
-   *   | 'hide' identifier (',' identifier)*
-   * </pre>
-   *
-   * @return the combinators that were parsed
+   *     combinator ::=
+   *         'show' identifier (',' identifier)*
+   *       | 'hide' identifier (',' identifier)*
    */
   List<Combinator> _parseCombinators() {
     List<Combinator> combinators = new List<Combinator>();
     while (true) {
       Combinator combinator = parseCombinator();
       if (combinator == null) {
         break;
       }
       combinators.add(combinator);
     }
     return combinators;
   }
 
   /**
-   * Parse the documentation comment and metadata preceding a declaration. This method allows any
-   * number of documentation comments to occur before, after or between the metadata, but only
-   * returns the last (right-most) documentation comment that is found.
+   * Parse the documentation comment and metadata preceding a declaration. This
+   * method allows any number of documentation comments to occur before, after
+   * or between the metadata, but only returns the last (right-most)
+   * documentation comment that is found. Return the documentation comment and
+   * metadata that were parsed.
    *
-   * <pre>
-   * metadata ::=
-   *     annotation*
-   * </pre>
-   *
-   * @return the documentation comment and metadata that were parsed
+   *     metadata ::=
+   *         annotation*
    */
   CommentAndMetadata _parseCommentAndMetadata() {
     Comment comment = _parseDocumentationComment();
     List<Annotation> metadata = new List<Annotation>();
     while (_matches(TokenType.AT)) {
       metadata.add(parseAnnotation());
       Comment optionalComment = _parseDocumentationComment();
       if (optionalComment != null) {
         comment = optionalComment;
       }
     }
     return new CommentAndMetadata(comment, metadata);
   }
 
   /**
-   * Parse a comment reference from the source between square brackets.
+   * Parse a comment reference from the source between square brackets. The
+   * [referenceSource] is the source occurring between the square brackets
+   * within a documentation comment. The [sourceOffset] is the offset of the
+   * first character of the reference source. Return the comment reference that
+   * was parsed, or `null` if no reference could be found.
    *
-   * <pre>
-   * commentReference ::=
-   *     'new'? prefixedIdentifier
-   * </pre>
-   *
-   * @param referenceSource the source occurring between the square brackets within a documentation
-   *          comment
-   * @param sourceOffset the offset of the first character of the reference source
-   * @return the comment reference that was parsed, or `null` if no reference could be found
+   *     commentReference ::=
+   *         'new'? prefixedIdentifier
    */
   CommentReference _parseCommentReference(
       String referenceSource, int sourceOffset) {
     // TODO(brianwilkerson) The errors are not getting the right offset/length
     // and are being duplicated.
     if (referenceSource.length == 0) {
       Token syntheticToken =
           new SyntheticStringToken(TokenType.IDENTIFIER, "", sourceOffset);
       return new CommentReference(null, new SimpleIdentifier(syntheticToken));
     }
@@ skipping 40 matching lines @@
         // approach.
         return null;
       }
     } catch (exception) {
       // Ignored because we assume that it wasn't a real comment reference.
     }
     return null;
   }
 
   /**
-   * Parse all of the comment references occurring in the given array of documentation comments.
+   * Parse all of the comment references occurring in the given array of
+   * documentation comments. The [tokens] are the comment tokens representing
+   * the documentation comments to be parsed. Return the comment references that
+   * were parsed.
    *
-   * <pre>
-   * commentReference ::=
-   *     '[' 'new'? qualified ']' libraryReference?
+   *     commentReference ::=
+   *         '[' 'new'? qualified ']' libraryReference?
    *
-   * libraryReference ::=
-   *      '(' stringLiteral ')'
-   * </pre>
-   *
-   * @param tokens the comment tokens representing the documentation comments to be parsed
-   * @return the comment references that were parsed
+   *     libraryReference ::=
+   *          '(' stringLiteral ')'
    */
   List<CommentReference> _parseCommentReferences(
       List<DocumentationCommentToken> tokens) {
     List<CommentReference> references = new List<CommentReference>();
     for (DocumentationCommentToken token in tokens) {
       String comment = token.lexeme;
       int length = comment.length;
       List<List<int>> codeBlockRanges = _getCodeBlockRanges(comment);
       int leftIndex = comment.indexOf('[');
       while (leftIndex >= 0 && leftIndex + 1 < length) {
@@ skipping 39 matching lines @@
           leftIndex = JavaString.indexOf(comment, '[', rightIndex);
         } else {
           leftIndex = JavaString.indexOf(comment, '[', range[1] + 1);
         }
       }
     }
     return references;
   }
 
   /**
-   * Parse a compilation unit member.
+   * Parse a compilation unit member. The [commentAndMetadata] is the metadata
+   * to be associated with the member. Return the compilation unit member that
+   * was parsed, or `null` if what was parsed could not be represented as a
+   * compilation unit member.
    *
-   * <pre>
-   * compilationUnitMember ::=
-   *     classDefinition
-   *   | functionTypeAlias
-   *   | external functionSignature
-   *   | external getterSignature
-   *   | external setterSignature
-   *   | functionSignature functionBody
-   *   | returnType? getOrSet identifier formalParameterList functionBody
-   *   | (final | const) type? staticFinalDeclarationList ';'
-   *   | variableDeclaration ';'
-   * </pre>
-   *
-   * @param commentAndMetadata the metadata to be associated with the member
-   * @return the compilation unit member that was parsed, or `null` if what was parsed could
-   *         not be represented as a compilation unit member
+   *     compilationUnitMember ::=
+   *         classDefinition
+   *       | functionTypeAlias
+   *       | external functionSignature
+   *       | external getterSignature
+   *       | external setterSignature
+   *       | functionSignature functionBody
+   *       | returnType? getOrSet identifier formalParameterList functionBody
+   *       | (final | const) type? staticFinalDeclarationList ';'
+   *       | variableDeclaration ';'
    */
   CompilationUnitMember _parseCompilationUnitMember(
       CommentAndMetadata commentAndMetadata) {
     Modifiers modifiers = _parseModifiers();
     if (_matchesKeyword(Keyword.CLASS)) {
       return _parseClassDeclaration(
           commentAndMetadata, _validateModifiersForClass(modifiers));
     } else if (_matchesKeyword(Keyword.TYPEDEF) &&
         !_tokenMatches(_peek(), TokenType.PERIOD) &&
         !_tokenMatches(_peek(), TokenType.LT) &&
@@ skipping 137 matching lines @@
       return _parseFunctionDeclaration(
           commentAndMetadata, modifiers.externalKeyword, returnType);
     }
     return new TopLevelVariableDeclaration(commentAndMetadata.comment,
         commentAndMetadata.metadata, _parseVariableDeclarationListAfterType(
             null, _validateModifiersForTopLevelVariable(modifiers), returnType),
         _expect(TokenType.SEMICOLON));
   }
 
   /**
-   * Parse a const expression.
+   * Parse a const expression. Return the const expression that was parsed.
    *
-   * <pre>
-   * constExpression ::=
-   *     instanceCreationExpression
-   *   | listLiteral
-   *   | mapLiteral
-   * </pre>
-   *
-   * @return the const expression that was parsed
+   *     constExpression ::=
+   *         instanceCreationExpression
+   *       | listLiteral
+   *       | mapLiteral
    */
   Expression _parseConstExpression() {
     Token keyword = _expectKeyword(Keyword.CONST);
     if (_matches(TokenType.OPEN_SQUARE_BRACKET) || _matches(TokenType.INDEX)) {
       return _parseListLiteral(keyword, null);
     } else if (_matches(TokenType.OPEN_CURLY_BRACKET)) {
       return _parseMapLiteral(keyword, null);
     } else if (_matches(TokenType.LT)) {
       return _parseListOrMapLiteral(keyword);
     }
@@ skipping 69 matching lines @@
         }
       }
     }
     return new ConstructorDeclaration(commentAndMetadata.comment,
         commentAndMetadata.metadata, externalKeyword, constKeyword,
         factoryKeyword, returnType, period, name, parameters, separator,
         initializers, redirectedConstructor, body);
   }
 
   /**
-   * Parse a field initializer within a constructor.
+   * Parse a field initializer within a constructor. Return the field
+   * initializer that was parsed.
    *
-   * <pre>
-   * fieldInitializer:
-   *     ('this' '.')? identifier '=' conditionalExpression cascadeSection*
-   * </pre>
-   *
-   * @return the field initializer that was parsed
+   *     fieldInitializer:
+   *         ('this' '.')? identifier '=' conditionalExpression cascadeSection*
    */
   ConstructorFieldInitializer _parseConstructorFieldInitializer() {
     Token keyword = null;
     Token period = null;
     if (_matchesKeyword(Keyword.THIS)) {
       keyword = getAndAdvance();
       period = _expect(TokenType.PERIOD);
     }
     SimpleIdentifier fieldName = parseSimpleIdentifier();
     Token equals = null;
@@ skipping 29 matching lines @@
         expression = new CascadeExpression(expression, cascadeSections);
       }
       return new ConstructorFieldInitializer(
           keyword, period, fieldName, equals, expression);
     } finally {
       _inInitializer = wasInInitializer;
     }
   }
 
   /**
-   * Parse a continue statement.
+   * Parse a continue statement. Return the continue statement that was parsed.
    *
-   * <pre>
-   * continueStatement ::=
-   *     'continue' identifier? ';'
-   * </pre>
-   *
-   * @return the continue statement that was parsed
+   *     continueStatement ::=
+   *         'continue' identifier? ';'
    */
   Statement _parseContinueStatement() {
     Token continueKeyword = _expectKeyword(Keyword.CONTINUE);
     if (!_inLoop && !_inSwitch) {
       _reportErrorForToken(
           ParserErrorCode.CONTINUE_OUTSIDE_OF_LOOP, continueKeyword);
     }
     SimpleIdentifier label = null;
     if (_matchesIdentifier()) {
       label = parseSimpleIdentifier();
     }
     if (_inSwitch && !_inLoop && label == null) {
       _reportErrorForToken(
           ParserErrorCode.CONTINUE_WITHOUT_LABEL_IN_CASE, continueKeyword);
     }
     Token semicolon = _expect(TokenType.SEMICOLON);
     return new ContinueStatement(continueKeyword, label, semicolon);
   }
 
   /**
-   * Parse a directive.
+   * Parse a directive. The [commentAndMetadata] is the metadata to be
+   * associated with the directive. Return the directive that was parsed.
    *
-   * <pre>
-   * directive ::=
-   *     exportDirective
-   *   | libraryDirective
-   *   | importDirective
-   *   | partDirective
-   * </pre>
-   *
-   * @param commentAndMetadata the metadata to be associated with the directive
-   * @return the directive that was parsed
+   *     directive ::=
+   *         exportDirective
+   *       | libraryDirective
+   *       | importDirective
+   *       | partDirective
    */
   Directive _parseDirective(CommentAndMetadata commentAndMetadata) {
     if (_matchesKeyword(Keyword.IMPORT)) {
       return _parseImportDirective(commentAndMetadata);
     } else if (_matchesKeyword(Keyword.EXPORT)) {
       return _parseExportDirective(commentAndMetadata);
     } else if (_matchesKeyword(Keyword.LIBRARY)) {
       return _parseLibraryDirective(commentAndMetadata);
     } else if (_matchesKeyword(Keyword.PART)) {
       return _parsePartDirective(commentAndMetadata);
     } else {
       // Internal error: this method should not have been invoked if the current
       // token was something other than one of the above.
       throw new IllegalStateException(
           "parseDirective invoked in an invalid state; currentToken = $_currentToken");
     }
   }
 
   /**
-   * Parse the script tag and directives in a compilation unit until the first non-directive is
-   * encountered.
+   * Parse the script tag and directives in a compilation unit until the first
+   * non-directive is encountered. Return the compilation unit that was parsed.
    *
-   *
-   * <pre>
-   * compilationUnit ::=
-   *     scriptTag? directive*
-   * </pre>
-   *
-   * @return the compilation unit that was parsed
+   *     compilationUnit ::=
+   *         scriptTag? directive*
    */
   CompilationUnit _parseDirectives() {
     Token firstToken = _currentToken;
     ScriptTag scriptTag = null;
     if (_matches(TokenType.SCRIPT_TAG)) {
       scriptTag = new ScriptTag(getAndAdvance());
     }
     List<Directive> directives = new List<Directive>();
     while (!_matches(TokenType.EOF)) {
       CommentAndMetadata commentAndMetadata = _parseCommentAndMetadata();
@@ skipping 13 matching lines @@
         }
         return new CompilationUnit(firstToken, scriptTag, directives,
             new List<CompilationUnitMember>(), _currentToken);
       }
     }
     return new CompilationUnit(firstToken, scriptTag, directives,
         new List<CompilationUnitMember>(), _currentToken);
   }
 
   /**
-   * Parse a documentation comment.
+   * Parse a documentation comment. Return the documentation comment that was
+   * parsed, or `null` if there was no comment.
    *
-   * <pre>
-   * documentationComment ::=
-   *     multiLineComment?
-   *   | singleLineComment*
-   * </pre>
-   *
-   * @return the documentation comment that was parsed, or `null` if there was no comment
+   *     documentationComment ::=
+   *         multiLineComment?
+   *       | singleLineComment*
    */
   Comment _parseDocumentationComment() {
     List<DocumentationCommentToken> documentationTokens =
         <DocumentationCommentToken>[];
     CommentToken commentToken = _currentToken.precedingComments;
     while (commentToken != null) {
       if (commentToken is DocumentationCommentToken) {
         if (documentationTokens.isNotEmpty) {
           if (commentToken.type == TokenType.SINGLE_LINE_COMMENT) {
             if (documentationTokens[0].type != TokenType.SINGLE_LINE_COMMENT) {
@@ skipping 10 matching lines @@
     if (documentationTokens.isEmpty) {
       return null;
     }
     List<CommentReference> references =
         _parseCommentReferences(documentationTokens);
     return Comment.createDocumentationCommentWithReferences(
         documentationTokens, references);
   }
 
   /**
-   * Parse a do statement.
+   * Parse a do statement. Return the do statement that was parsed.
    *
-   * <pre>
-   * doStatement ::=
-   *     'do' statement 'while' '(' expression ')' ';'
-   * </pre>
-   *
-   * @return the do statement that was parsed
+   *     doStatement ::=
+   *         'do' statement 'while' '(' expression ')' ';'
    */
   Statement _parseDoStatement() {
     bool wasInLoop = _inLoop;
     _inLoop = true;
     try {
       Token doKeyword = _expectKeyword(Keyword.DO);
       Statement body = parseStatement2();
       Token whileKeyword = _expectKeyword(Keyword.WHILE);
       Token leftParenthesis = _expect(TokenType.OPEN_PAREN);
       Expression condition = parseExpression2();
       Token rightParenthesis = _expect(TokenType.CLOSE_PAREN);
       Token semicolon = _expect(TokenType.SEMICOLON);
       return new DoStatement(doKeyword, body, whileKeyword, leftParenthesis,
           condition, rightParenthesis, semicolon);
     } finally {
       _inLoop = wasInLoop;
     }
   }
 
   /**
-   * Parse an empty statement.
+   * Parse an empty statement. Return the empty statement that was parsed.
    *
-   * <pre>
-   * emptyStatement ::=
-   *     ';'
-   * </pre>
-   *
-   * @return the empty statement that was parsed
+   *     emptyStatement ::=
+   *         ';'
    */
   Statement _parseEmptyStatement() => new EmptyStatement(getAndAdvance());
 
   EnumConstantDeclaration _parseEnumConstantDeclaration() {
     CommentAndMetadata commentAndMetadata = _parseCommentAndMetadata();
     SimpleIdentifier name;
     if (_matchesIdentifier()) {
       name = parseSimpleIdentifier();
     } else {
       name = _createSyntheticIdentifier();
     }
     if (commentAndMetadata.metadata.isNotEmpty) {
       _reportErrorForNode(ParserErrorCode.ANNOTATION_ON_ENUM_CONSTANT,
           commentAndMetadata.metadata[0]);
     }
     return new EnumConstantDeclaration(
         commentAndMetadata.comment, commentAndMetadata.metadata, name);
   }
 
   /**
-   * Parse an enum declaration.
+   * Parse an enum declaration. The [commentAndMetadata] is the metadata to be
+   * associated with the member. Return the enum declaration that was parsed.
    *
-   * <pre>
-   * enumType ::=
-   *     metadata 'enum' id '{' id (',' id)* (',')? '}'
-   * </pre>
-   *
-   * @param commentAndMetadata the metadata to be associated with the member
-   * @return the enum declaration that was parsed
+   *     enumType ::=
+   *         metadata 'enum' id '{' id (',' id)* (',')? '}'
    */
   EnumDeclaration _parseEnumDeclaration(CommentAndMetadata commentAndMetadata) {
     Token keyword = _expectKeyword(Keyword.ENUM);
     SimpleIdentifier name = parseSimpleIdentifier();
     Token leftBracket = null;
     List<EnumConstantDeclaration> constants =
         new List<EnumConstantDeclaration>();
     Token rightBracket = null;
     if (_matches(TokenType.OPEN_CURLY_BRACKET)) {
       leftBracket = _expect(TokenType.OPEN_CURLY_BRACKET);
@@ skipping 18 matching lines @@
       leftBracket = _createSyntheticToken(TokenType.OPEN_CURLY_BRACKET);
       rightBracket = _createSyntheticToken(TokenType.CLOSE_CURLY_BRACKET);
       _reportErrorForCurrentToken(ParserErrorCode.MISSING_ENUM_BODY);
     }
     return new EnumDeclaration(commentAndMetadata.comment,
         commentAndMetadata.metadata, keyword, name, leftBracket, constants,
         rightBracket);
   }
 
   /**
-   * Parse an equality expression.
+   * Parse an equality expression. Return the equality expression that was
+   * parsed.
    *
-   * <pre>
-   * equalityExpression ::=
-   *     relationalExpression (equalityOperator relationalExpression)?
-   *   | 'super' equalityOperator relationalExpression
-   * </pre>
-   *
-   * @return the equality expression that was parsed
+   *     equalityExpression ::=
+   *         relationalExpression (equalityOperator relationalExpression)?
+   *       | 'super' equalityOperator relationalExpression
    */
   Expression _parseEqualityExpression() {
     Expression expression;
     if (_matchesKeyword(Keyword.SUPER) &&
         _currentToken.next.type.isEqualityOperator) {
       expression = new SuperExpression(getAndAdvance());
     } else {
       expression = _parseRelationalExpression();
     }
     bool leftEqualityExpression = false;
     while (_currentToken.type.isEqualityOperator) {
       Token operator = getAndAdvance();
       if (leftEqualityExpression) {
         _reportErrorForNode(
             ParserErrorCode.EQUALITY_CANNOT_BE_EQUALITY_OPERAND, expression);
       }
       expression = new BinaryExpression(
           expression, operator, _parseRelationalExpression());
       leftEqualityExpression = true;
     }
     return expression;
   }
 
   /**
-   * Parse an export directive.
+   * Parse an export directive. The [commentAndMetadata] is the metadata to be
+   * associated with the directive. Return the export directive that was parsed.
    *
-   * <pre>
-   * exportDirective ::=
-   *     metadata 'export' stringLiteral combinator*';'
-   * </pre>
-   *
-   * @param commentAndMetadata the metadata to be associated with the directive
-   * @return the export directive that was parsed
+   *     exportDirective ::=
+   *         metadata 'export' stringLiteral combinator*';'
    */
   ExportDirective _parseExportDirective(CommentAndMetadata commentAndMetadata) {
     Token exportKeyword = _expectKeyword(Keyword.EXPORT);
     StringLiteral libraryUri = _parseUri();
     List<Combinator> combinators = _parseCombinators();
     Token semicolon = _expectSemicolon();
     return new ExportDirective(commentAndMetadata.comment,
         commentAndMetadata.metadata, exportKeyword, libraryUri, combinators,
         semicolon);
   }
 
   /**
-   * Parse a list of expressions.
+   * Parse a list of expressions. Return the expression that was parsed.
    *
-   * <pre>
-   * expressionList ::=
-   *     expression (',' expression)*
-   * </pre>
-   *
-   * @return the expression that was parsed
+   *     expressionList ::=
+   *         expression (',' expression)*
    */
   List<Expression> _parseExpressionList() {
     List<Expression> expressions = new List<Expression>();
     expressions.add(parseExpression2());
     while (_optional(TokenType.COMMA)) {
       expressions.add(parseExpression2());
     }
     return expressions;
   }
 
   /**
    * Parse the 'final', 'const', 'var' or type preceding a variable declaration.
+   * The [optional] is `true` if the keyword and type are optional. Return the
+   * 'final', 'const', 'var' or type that was parsed.
    *
-   * <pre>
-   * finalConstVarOrType ::=
-   *   | 'final' type?
-   *   | 'const' type?
-   *   | 'var'
-   *   | type
-   * </pre>
-   *
-   * @param optional `true` if the keyword and type are optional
-   * @return the 'final', 'const', 'var' or type that was parsed
+   *     finalConstVarOrType ::=
+   *         'final' type?
+   *       | 'const' type?
+   *       | 'var'
+   *       | type
    */
   FinalConstVarOrType _parseFinalConstVarOrType(bool optional) {
     Token keyword = null;
     TypeName type = null;
     if (_matchesKeyword(Keyword.FINAL) || _matchesKeyword(Keyword.CONST)) {
       keyword = getAndAdvance();
       if (_isTypedIdentifier(_currentToken)) {
         type = parseTypeName();
       }
     } else if (_matchesKeyword(Keyword.VAR)) {
       keyword = getAndAdvance();
     } else {
       if (_isTypedIdentifier(_currentToken)) {
         type = parseReturnType();
       } else if (!optional) {
         _reportErrorForCurrentToken(
             ParserErrorCode.MISSING_CONST_FINAL_VAR_OR_TYPE);
       }
     }
     return new FinalConstVarOrType(keyword, type);
   }
 
   /**
    * Parse a formal parameter. At most one of `isOptional` and `isNamed` can be
-   * `true`.
+   * `true`. The [kind] is the kind of parameter being expected based on the
+   * presence or absence of group delimiters. Return the formal parameter that
+   * was parsed.
    *
-   * <pre>
-   * defaultFormalParameter ::=
-   *     normalFormalParameter ('=' expression)?
+   *     defaultFormalParameter ::=
+   *         normalFormalParameter ('=' expression)?
    *
-   * defaultNamedParameter ::=
-   *     normalFormalParameter (':' expression)?
-   * </pre>
-   *
-   * @param kind the kind of parameter being expected based on the presence or absence of group
-   *          delimiters
-   * @return the formal parameter that was parsed
+   *     defaultNamedParameter ::=
+   *         normalFormalParameter (':' expression)?
    */
   FormalParameter _parseFormalParameter(ParameterKind kind) {
     NormalFormalParameter parameter = parseNormalFormalParameter();
     if (_matches(TokenType.EQ)) {
       Token seperator = getAndAdvance();
       Expression defaultValue = parseExpression2();
       if (kind == ParameterKind.NAMED) {
         _reportErrorForToken(
             ParserErrorCode.WRONG_SEPARATOR_FOR_NAMED_PARAMETER, seperator);
       } else if (kind == ParameterKind.REQUIRED) {
@@ skipping 15 matching lines @@
       }
       return new DefaultFormalParameter(
           parameter, kind, seperator, defaultValue);
     } else if (kind != ParameterKind.REQUIRED) {
       return new DefaultFormalParameter(parameter, kind, null, null);
     }
     return parameter;
   }
 
   /**
-   * Parse a for statement.
+   * Parse a for statement. Return the for statement that was parsed.
    *
-   * <pre>
-   * forStatement ::=
-   *     'for' '(' forLoopParts ')' statement
+   *     forStatement ::=
+   *         'for' '(' forLoopParts ')' statement
    *
-   * forLoopParts ::=
-   *     forInitializerStatement expression? ';' expressionList?
-   *   | declaredIdentifier 'in' expression
-   *   | identifier 'in' expression
+   *     forLoopParts ::=
+   *         forInitializerStatement expression? ';' expressionList?
+   *       | declaredIdentifier 'in' expression
+   *       | identifier 'in' expression
    *
-   * forInitializerStatement ::=
-   *     localVariableDeclaration ';'
-   *   | expression? ';'
-   * </pre>
-   *
-   * @return the for statement that was parsed
+   *     forInitializerStatement ::=
+   *         localVariableDeclaration ';'
+   *       | expression? ';'
    */
   Statement _parseForStatement() {
     bool wasInLoop = _inLoop;
     _inLoop = true;
     try {
       Token awaitKeyword = null;
       if (_matchesString(_AWAIT)) {
         awaitKeyword = getAndAdvance();
       }
       Token forKeyword = _expectKeyword(Keyword.FOR);
@@ skipping 86 matching lines @@
       Statement body = parseStatement2();
       return new ForStatement(forKeyword, leftParenthesis, variableList,
           initialization, leftSeparator, condition, rightSeparator, updaters,
           rightParenthesis, body);
     } finally {
       _inLoop = wasInLoop;
     }
   }
 
   /**
-   * Parse a function body.
+   * Parse a function body. The [mayBeEmpty] is `true` if the function body is
+   * allowed to be empty. The [emptyErrorCode] is the error code to report if
+   * function body expected, but not found. The [inExpression] is `true` if the
+   * function body is being parsed as part of an expression and therefore does
+   * not have a terminating semicolon. Return the function body that was parsed.
    *
-   * <pre>
-   * functionBody ::=
-   *     '=>' expression ';'
-   *   | block
+   *     functionBody ::=
+   *         '=>' expression ';'
+   *       | block
    *
-   * functionExpressionBody ::=
-   *     '=>' expression
-   *   | block
-   * </pre>
-   *
-   * @param mayBeEmpty `true` if the function body is allowed to be empty
-   * @param emptyErrorCode the error code to report if function body expected, but not found
-   * @param inExpression `true` if the function body is being parsed as part of an expression
-   *          and therefore does not have a terminating semicolon
-   * @return the function body that was parsed
+   *     functionExpressionBody ::=
+   *         '=>' expression
+   *       | block
    */
   FunctionBody _parseFunctionBody(
       bool mayBeEmpty, ParserErrorCode emptyErrorCode, bool inExpression) {
     bool wasInAsync = _inAsync;
     bool wasInGenerator = _inGenerator;
     bool wasInLoop = _inLoop;
     bool wasInSwitch = _inSwitch;
     _inAsync = false;
     _inGenerator = false;
     _inLoop = false;
@@ skipping 76 matching lines @@
       }
     } finally {
       _inAsync = wasInAsync;
       _inGenerator = wasInGenerator;
       _inLoop = wasInLoop;
       _inSwitch = wasInSwitch;
     }
   }
 
   /**
-   * Parse a function declaration.
+   * Parse a function declaration. The [commentAndMetadata] is the documentation
+   * comment and metadata to be associated with the declaration. The
+   * [externalKeyword] is the 'external' keyword, or `null` if the function is
+   * not external. The [returnType] is the return type, or `null` if there is no
+   * return type. The [isStatement] is `true` if the function declaration is
+   * being parsed as a statement. Return the function declaration that was
+   * parsed.
    *
-   * <pre>
-   * functionDeclaration ::=
-   *     functionSignature functionBody
-   *   | returnType? getOrSet identifier formalParameterList functionBody
-   * </pre>
-   *
-   * @param commentAndMetadata the documentation comment and metadata to be associated with the
-   *          declaration
-   * @param externalKeyword the 'external' keyword, or `null` if the function is not external
-   * @param returnType the return type, or `null` if there is no return type
-   * @param isStatement `true` if the function declaration is being parsed as a statement
-   * @return the function declaration that was parsed
+   *     functionDeclaration ::=
+   *         functionSignature functionBody
+   *       | returnType? getOrSet identifier formalParameterList functionBody
    */
   FunctionDeclaration _parseFunctionDeclaration(
       CommentAndMetadata commentAndMetadata, Token externalKeyword,
       TypeName returnType) {
     Token keyword = null;
     bool isGetter = false;
     if (_matchesKeyword(Keyword.GET) &&
         !_tokenMatches(_peek(), TokenType.OPEN_PAREN)) {
       keyword = getAndAdvance();
       isGetter = true;
@@ skipping 26 matching lines @@
 //          // TODO(brianwilkerson) Improve this error message.
 //          reportError(ParserErrorCode.UNEXPECTED_TOKEN, currentToken.getLexeme());
 //          advance();
 //        }
     return new FunctionDeclaration(commentAndMetadata.comment,
         commentAndMetadata.metadata, externalKeyword, returnType, keyword, name,
         new FunctionExpression(parameters, body));
   }
 
   /**
-   * Parse a function declaration statement.
+   * Parse a function declaration statement. Return the function declaration
+   * statement that was parsed.
    *
-   * <pre>
-   * functionDeclarationStatement ::=
-   *     functionSignature functionBody
-   * </pre>
-   *
-   * @return the function declaration statement that was parsed
+   *     functionDeclarationStatement ::=
+   *         functionSignature functionBody
    */
   Statement _parseFunctionDeclarationStatement() {
     Modifiers modifiers = _parseModifiers();
     _validateModifiersForFunctionDeclarationStatement(modifiers);
     return _parseFunctionDeclarationStatementAfterReturnType(
         _parseCommentAndMetadata(), _parseOptionalReturnType());
   }
 
   /**
-   * Parse a function declaration statement.
+   * Parse a function declaration statement. The [commentAndMetadata] is the
+   * documentation comment and metadata to be associated with the declaration.
+   * The [returnType] is the return type, or `null` if there is no return type.
+   * Return the function declaration statement that was parsed.
    *
-   * <pre>
-   * functionDeclarationStatement ::=
-   *     functionSignature functionBody
-   * </pre>
-   *
-   * @param commentAndMetadata the documentation comment and metadata to be associated with the
-   *          declaration
-   * @param returnType the return type, or `null` if there is no return type
-   * @return the function declaration statement that was parsed
+   *     functionDeclarationStatement ::=
+   *         functionSignature functionBody
    */
   Statement _parseFunctionDeclarationStatementAfterReturnType(
       CommentAndMetadata commentAndMetadata, TypeName returnType) {
     FunctionDeclaration declaration =
         _parseFunctionDeclaration(commentAndMetadata, null, returnType);
     Token propertyKeyword = declaration.propertyKeyword;
     if (propertyKeyword != null) {
       if ((propertyKeyword as KeywordToken).keyword == Keyword.GET) {
         _reportErrorForToken(
             ParserErrorCode.GETTER_IN_FUNCTION, propertyKeyword);
       } else {
         _reportErrorForToken(
             ParserErrorCode.SETTER_IN_FUNCTION, propertyKeyword);
       }
     }
     return new FunctionDeclarationStatement(declaration);
   }
 
   /**
-   * Parse a function type alias.
+   * Parse a function type alias. The [commentAndMetadata] is the metadata to be
+   * associated with the member. The [keyword] is the token representing the
+   * 'typedef' keyword. Return the function type alias that was parsed.
    *
-   * <pre>
-   * functionTypeAlias ::=
-   *     functionPrefix typeParameterList? formalParameterList ';'
+   *     functionTypeAlias ::=
+   *         functionPrefix typeParameterList? formalParameterList ';'
    *
-   * functionPrefix ::=
-   *     returnType? name
-   * </pre>
-   *
-   * @param commentAndMetadata the metadata to be associated with the member
-   * @param keyword the token representing the 'typedef' keyword
-   * @return the function type alias that was parsed
+   *     functionPrefix ::=
+   *         returnType? name
    */
   FunctionTypeAlias _parseFunctionTypeAlias(
       CommentAndMetadata commentAndMetadata, Token keyword) {
     TypeName returnType = null;
     if (hasReturnTypeInTypeAlias) {
       returnType = parseReturnType();
     }
     SimpleIdentifier name = parseSimpleIdentifier();
     TypeParameterList typeParameters = null;
     if (_matches(TokenType.LT)) {
@@ skipping 23 matching lines @@
     }
     FormalParameterList parameters = parseFormalParameterList();
     _validateFormalParameterList(parameters);
     Token semicolon = _expect(TokenType.SEMICOLON);
     return new FunctionTypeAlias(commentAndMetadata.comment,
         commentAndMetadata.metadata, keyword, returnType, name, typeParameters,
         parameters, semicolon);
   }
 
   /**
-   * Parse a getter.
+   * Parse a getter. The [commentAndMetadata] is the documentation comment and
+   * metadata to be associated with the declaration. The externalKeyword] is the
+   * 'external' token. The staticKeyword] is the static keyword, or `null` if
+   * the getter is not static. The [returnType] the return type that has already
+   * been parsed, or `null` if there was no return type. Return the getter that
+   * was parsed.
    *
-   * <pre>
-   * getter ::=
-   *     getterSignature functionBody?
+   *     getter ::=
+   *         getterSignature functionBody?
    *
-   * getterSignature ::=
-   *     'external'? 'static'? returnType? 'get' identifier
-   * </pre>
-   *
-   * @param commentAndMetadata the documentation comment and metadata to be associated with the
-   *          declaration
-   * @param externalKeyword the 'external' token
-   * @param staticKeyword the static keyword, or `null` if the getter is not static
-   * @param the return type that has already been parsed, or `null` if there was no return
-   *          type
-   * @return the getter that was parsed
+   *     getterSignature ::=
+   *         'external'? 'static'? returnType? 'get' identifier
    */
   MethodDeclaration _parseGetter(CommentAndMetadata commentAndMetadata,
       Token externalKeyword, Token staticKeyword, TypeName returnType) {
     Token propertyKeyword = _expectKeyword(Keyword.GET);
     SimpleIdentifier name = parseSimpleIdentifier();
     if (_matches(TokenType.OPEN_PAREN) &&
         _tokenMatches(_peek(), TokenType.CLOSE_PAREN)) {
       _reportErrorForCurrentToken(ParserErrorCode.GETTER_WITH_PARAMETERS);
       _advance();
       _advance();
     }
     FunctionBody body = _parseFunctionBody(
         externalKeyword != null || staticKeyword == null,
         ParserErrorCode.STATIC_GETTER_WITHOUT_BODY, false);
     if (externalKeyword != null && body is! EmptyFunctionBody) {
       _reportErrorForCurrentToken(ParserErrorCode.EXTERNAL_GETTER_WITH_BODY);
     }
     return new MethodDeclaration(commentAndMetadata.comment,
         commentAndMetadata.metadata, externalKeyword, staticKeyword, returnType,
         propertyKeyword, null, name, null, body);
   }
 
   /**
-   * Parse a list of identifiers.
+   * Parse a list of identifiers. Return the list of identifiers that were
+   * parsed.
    *
-   * <pre>
-   * identifierList ::=
-   *     identifier (',' identifier)*
-   * </pre>
-   *
-   * @return the list of identifiers that were parsed
+   *     identifierList ::=
+   *         identifier (',' identifier)*
    */
   List<SimpleIdentifier> _parseIdentifierList() {
     List<SimpleIdentifier> identifiers = new List<SimpleIdentifier>();
     identifiers.add(parseSimpleIdentifier());
     while (_matches(TokenType.COMMA)) {
       _advance();
       identifiers.add(parseSimpleIdentifier());
     }
     return identifiers;
   }
 
   /**
-   * Parse an if statement.
+   * Parse an if statement. Return the if statement that was parsed.
    *
-   * <pre>
-   * ifStatement ::=
-   *     'if' '(' expression ')' statement ('else' statement)?
-   * </pre>
-   *
-   * @return the if statement that was parsed
+   *     ifStatement ::=
+   *         'if' '(' expression ')' statement ('else' statement)?
    */
   Statement _parseIfStatement() {
     Token ifKeyword = _expectKeyword(Keyword.IF);
     Token leftParenthesis = _expect(TokenType.OPEN_PAREN);
     Expression condition = parseExpression2();
     Token rightParenthesis = _expect(TokenType.CLOSE_PAREN);
     Statement thenStatement = parseStatement2();
     Token elseKeyword = null;
     Statement elseStatement = null;
     if (_matchesKeyword(Keyword.ELSE)) {
       elseKeyword = getAndAdvance();
       elseStatement = parseStatement2();
     }
     return new IfStatement(ifKeyword, leftParenthesis, condition,
         rightParenthesis, thenStatement, elseKeyword, elseStatement);
   }
 
   /**
-   * Parse an import directive.
+   * Parse an import directive. The [commentAndMetadata] is the metadata to be
+   * associated with the directive. Return the import directive that was parsed.
    *
-   * <pre>
-   * importDirective ::=
-   *     metadata 'import' stringLiteral ('as' identifier)? combinator*';'
-   * </pre>
-   *
-   * @param commentAndMetadata the metadata to be associated with the directive
-   * @return the import directive that was parsed
+   *     importDirective ::=
+   *         metadata 'import' stringLiteral ('as' identifier)? combinator*';'
    */
   ImportDirective _parseImportDirective(CommentAndMetadata commentAndMetadata) {
     Token importKeyword = _expectKeyword(Keyword.IMPORT);
     StringLiteral libraryUri = _parseUri();
     Token deferredToken = null;
     Token asToken = null;
     SimpleIdentifier prefix = null;
     if (_matchesKeyword(Keyword.DEFERRED)) {
       deferredToken = getAndAdvance();
     }
     if (_matchesKeyword(Keyword.AS)) {
       asToken = getAndAdvance();
       prefix = parseSimpleIdentifier();
     } else if (deferredToken != null) {
       _reportErrorForCurrentToken(
           ParserErrorCode.MISSING_PREFIX_IN_DEFERRED_IMPORT);
     }
     List<Combinator> combinators = _parseCombinators();
     Token semicolon = _expectSemicolon();
     return new ImportDirective(commentAndMetadata.comment,
         commentAndMetadata.metadata, importKeyword, libraryUri, deferredToken,
         asToken, prefix, combinators, semicolon);
   }
 
   /**
-   * Parse a list of initialized identifiers.
+   * Parse a list of initialized identifiers. The [commentAndMetadata] is the
+   * documentation comment and metadata to be associated with the declaration.
+   * The [staticKeyword] is the static keyword, or `null` if the getter is not
+   * static. The [keyword] is the token representing the 'final', 'const' or
+   * 'var' keyword, or `null` if there is no keyword. The [type] is the type
+   * that has already been parsed, or `null` if 'var' was provided. Return the
+   * getter that was parsed.
    *
-   * <pre>
-   * ?? ::=
-   *     'static'? ('var' | type) initializedIdentifierList ';'
-   *   | 'final' type? initializedIdentifierList ';'
+   *     ?? ::=
+   *         'static'? ('var' | type) initializedIdentifierList ';'
+   *       | 'final' type? initializedIdentifierList ';'
    *
-   * initializedIdentifierList ::=
-   *     initializedIdentifier (',' initializedIdentifier)*
+   *     initializedIdentifierList ::=
+   *         initializedIdentifier (',' initializedIdentifier)*
    *
-   * initializedIdentifier ::=
-   *     identifier ('=' expression)?
-   * </pre>
-   *
-   * @param commentAndMetadata the documentation comment and metadata to be associated with the
-   *          declaration
-   * @param staticKeyword the static keyword, or `null` if the getter is not static
-   * @param keyword the token representing the 'final', 'const' or 'var' keyword, or `null` if
-   *          there is no keyword
-   * @param type the type that has already been parsed, or `null` if 'var' was provided
-   * @return the getter that was parsed
+   *     initializedIdentifier ::=
+   *         identifier ('=' expression)?
    */
   FieldDeclaration _parseInitializedIdentifierList(
       CommentAndMetadata commentAndMetadata, Token staticKeyword, Token keyword,
       TypeName type) {
     VariableDeclarationList fieldList =
         _parseVariableDeclarationListAfterType(null, keyword, type);
     return new FieldDeclaration(commentAndMetadata.comment,
         commentAndMetadata.metadata, staticKeyword, fieldList,
         _expect(TokenType.SEMICOLON));
   }
 
   /**
-   * Parse an instance creation expression.
+   * Parse an instance creation expression. The [keyword] is the 'new' or
+   * 'const' keyword that introduces the expression. Return the instance
+   * creation expression that was parsed.
    *
-   * <pre>
-   * instanceCreationExpression ::=
-   *     ('new' | 'const') type ('.' identifier)? argumentList
-   * </pre>
-   *
-   * @param keyword the 'new' or 'const' keyword that introduces the expression
-   * @return the instance creation expression that was parsed
+   *     instanceCreationExpression ::=
+   *         ('new' | 'const') type ('.' identifier)? argumentList
    */
   InstanceCreationExpression _parseInstanceCreationExpression(Token keyword) {
     ConstructorName constructorName = parseConstructorName();
     ArgumentList argumentList = parseArgumentList();
     return new InstanceCreationExpression(
         keyword, constructorName, argumentList);
   }
 
   /**
-   * Parse a library directive.
+   * Parse a library directive. The [commentAndMetadata] is the metadata to be
+   * associated with the directive. Return the library directive that was
+   * parsed.
    *
-   * <pre>
-   * libraryDirective ::=
-   *     metadata 'library' identifier ';'
-   * </pre>
-   *
-   * @param commentAndMetadata the metadata to be associated with the directive
-   * @return the library directive that was parsed
+   *     libraryDirective ::=
+   *         metadata 'library' identifier ';'
    */
   LibraryDirective _parseLibraryDirective(
       CommentAndMetadata commentAndMetadata) {
     Token keyword = _expectKeyword(Keyword.LIBRARY);
     LibraryIdentifier libraryName = _parseLibraryName(
         ParserErrorCode.MISSING_NAME_IN_LIBRARY_DIRECTIVE, keyword);
     Token semicolon = _expect(TokenType.SEMICOLON);
     return new LibraryDirective(commentAndMetadata.comment,
         commentAndMetadata.metadata, keyword, libraryName, semicolon);
   }
 
   /**
-   * Parse a library name.
+   * Parse a library name. The [missingNameError] is the error code to be used
+   * if the library name is missing. The [missingNameToken] is the token
+   * associated with the error produced if the library name is missing. Return
+   * the library name that was parsed.
    *
-   * <pre>
-   * libraryName ::=
-   *     libraryIdentifier
-   * </pre>
-   *
-   * @param missingNameError the error code to be used if the library name is missing
-   * @param missingNameToken the token associated with the error produced if the library name is
-   *          missing
-   * @return the library name that was parsed
+   *     libraryName ::=
+   *         libraryIdentifier
    */
   LibraryIdentifier _parseLibraryName(
       ParserErrorCode missingNameError, Token missingNameToken) {
     if (_matchesIdentifier()) {
       return parseLibraryIdentifier();
     } else if (_matches(TokenType.STRING)) {
       // TODO(brianwilkerson) Recovery: This should be extended to handle
       // arbitrary tokens until we can find a token that can start a compilation
       // unit member.
       StringLiteral string = parseStringLiteral();
       _reportErrorForNode(ParserErrorCode.NON_IDENTIFIER_LIBRARY_NAME, string);
     } else {
       _reportErrorForToken(missingNameError, missingNameToken);
     }
     List<SimpleIdentifier> components = new List<SimpleIdentifier>();
     components.add(_createSyntheticIdentifier());
     return new LibraryIdentifier(components);
   }
 
   /**
-   * Parse a list literal.
+   * Parse a list literal. The [modifier] is the 'const' modifier appearing
+   * before the literal, or `null` if there is no modifier. The [typeArguments]
+   * is the type arguments appearing before the literal, or `null` if there are
+   * no type arguments. Return the list literal that was parsed.
    *
-   * <pre>
-   * listLiteral ::=
-   *     'const'? typeArguments? '[' (expressionList ','?)? ']'
-   * </pre>
-   *
-   * @param modifier the 'const' modifier appearing before the literal, or `null` if there is
-   *          no modifier
-   * @param typeArguments the type arguments appearing before the literal, or `null` if there
-   *          are no type arguments
-   * @return the list literal that was parsed
+   *     listLiteral ::=
+   *         'const'? typeArguments? '[' (expressionList ','?)? ']'
    */
   ListLiteral _parseListLiteral(
       Token modifier, TypeArgumentList typeArguments) {
     // may be empty list literal
     if (_matches(TokenType.INDEX)) {
       BeginToken leftBracket = _createToken(
           _currentToken, TokenType.OPEN_SQUARE_BRACKET, isBegin: true);
       Token rightBracket =
           new Token(TokenType.CLOSE_SQUARE_BRACKET, _currentToken.offset + 1);
       leftBracket.endToken = rightBracket;
@@ skipping 24 matching lines @@
       }
       Token rightBracket = _expect(TokenType.CLOSE_SQUARE_BRACKET);
       return new ListLiteral(
           modifier, typeArguments, leftBracket, elements, rightBracket);
     } finally {
       _inInitializer = wasInInitializer;
     }
   }
 
   /**
-   * Parse a list or map literal.
+   * Parse a list or map literal. The [modifier] is the 'const' modifier
+   * appearing before the literal, or `null` if there is no modifier. Return the
+   * list or map literal that was parsed.
    *
-   * <pre>
-   * listOrMapLiteral ::=
-   *     listLiteral
-   *   | mapLiteral
-   * </pre>
-   *
-   * @param modifier the 'const' modifier appearing before the literal, or `null` if there is
-   *          no modifier
-   * @return the list or map literal that was parsed
+   *     listOrMapLiteral ::=
+   *         listLiteral
+   *       | mapLiteral
    */
   TypedLiteral _parseListOrMapLiteral(Token modifier) {
     TypeArgumentList typeArguments = null;
     if (_matches(TokenType.LT)) {
       typeArguments = parseTypeArgumentList();
     }
     if (_matches(TokenType.OPEN_CURLY_BRACKET)) {
       return _parseMapLiteral(modifier, typeArguments);
     } else if (_matches(TokenType.OPEN_SQUARE_BRACKET) ||
         _matches(TokenType.INDEX)) {
       return _parseListLiteral(modifier, typeArguments);
     }
     _reportErrorForCurrentToken(ParserErrorCode.EXPECTED_LIST_OR_MAP_LITERAL);
     return new ListLiteral(modifier, typeArguments,
         _createSyntheticToken(TokenType.OPEN_SQUARE_BRACKET), null,
         _createSyntheticToken(TokenType.CLOSE_SQUARE_BRACKET));
   }
 
   /**
-   * Parse a logical and expression.
+   * Parse a logical and expression. Return the logical and expression that was
+   * parsed.
    *
-   * <pre>
-   * logicalAndExpression ::=
-   *     equalityExpression ('&&' equalityExpression)*
-   * </pre>
-   *
-   * @return the logical and expression that was parsed
+   *     logicalAndExpression ::=
+   *         equalityExpression ('&&' equalityExpression)*
    */
   Expression _parseLogicalAndExpression() {
     Expression expression = _parseEqualityExpression();
     while (_matches(TokenType.AMPERSAND_AMPERSAND)) {
       Token operator = getAndAdvance();
       expression = new BinaryExpression(
           expression, operator, _parseEqualityExpression());
     }
     return expression;
   }
 
   /**
-   * Parse a map literal.
+   * Parse a map literal. The [modifier] is the 'const' modifier appearing
+   * before the literal, or `null` if there is no modifier. The [typeArguments]
+   * is the type arguments that were declared, or `null` if there are no type
+   * arguments. Return the map literal that was parsed.
    *
-   * <pre>
-   * mapLiteral ::=
-   *     'const'? typeArguments? '{' (mapLiteralEntry (',' mapLiteralEntry)* ','?)? '}'
-   * </pre>
-   *
-   * @param modifier the 'const' modifier appearing before the literal, or `null` if there is
-   *          no modifier
-   * @param typeArguments the type arguments that were declared, or `null` if there are no
-   *          type arguments
-   * @return the map literal that was parsed
+   *     mapLiteral ::=
+   *         'const'? typeArguments? '{' (mapLiteralEntry (',' mapLiteralEntry)* ','?)? '}'
    */
   MapLiteral _parseMapLiteral(Token modifier, TypeArgumentList typeArguments) {
     Token leftBracket = _expect(TokenType.OPEN_CURLY_BRACKET);
     List<MapLiteralEntry> entries = new List<MapLiteralEntry>();
     if (_matches(TokenType.CLOSE_CURLY_BRACKET)) {
       return new MapLiteral(
           modifier, typeArguments, leftBracket, entries, getAndAdvance());
     }
     bool wasInInitializer = _inInitializer;
     _inInitializer = false;
     try {
       entries.add(parseMapLiteralEntry());
       while (_optional(TokenType.COMMA)) {
         if (_matches(TokenType.CLOSE_CURLY_BRACKET)) {
           return new MapLiteral(
               modifier, typeArguments, leftBracket, entries, getAndAdvance());
         }
         entries.add(parseMapLiteralEntry());
       }
       Token rightBracket = _expect(TokenType.CLOSE_CURLY_BRACKET);
       return new MapLiteral(
           modifier, typeArguments, leftBracket, entries, rightBracket);
     } finally {
       _inInitializer = wasInInitializer;
     }
   }
 
   /**
-   * Parse a method declaration.
+   * Parse a method declaration. The [commentAndMetadata] is the documentation
+   * comment and metadata to be associated with the declaration. The
+   * [externalKeyword] is the 'external' token. The [staticKeyword] is the
+   * static keyword, or `null` if the getter is not static. The [returnType] is
+   * the return type of the method. The [name] is the name of the method. The
+   * [parameters] is the parameters to the method. Return the method declaration
+   * that was parsed.
    *
-   * <pre>
-   * functionDeclaration ::=
-   *     ('external' 'static'?)? functionSignature functionBody
-   *   | 'external'? functionSignature ';'
-   * </pre>
-   *
-   * @param commentAndMetadata the documentation comment and metadata to be associated with the
-   *          declaration
-   * @param externalKeyword the 'external' token
-   * @param staticKeyword the static keyword, or `null` if the getter is not static
-   * @param returnType the return type of the method
-   * @param name the name of the method
-   * @param parameters the parameters to the method
-   * @return the method declaration that was parsed
+   *     functionDeclaration ::=
+   *         ('external' 'static'?)? functionSignature functionBody
+   *       | 'external'? functionSignature ';'
    */
   MethodDeclaration _parseMethodDeclarationAfterParameters(
       CommentAndMetadata commentAndMetadata, Token externalKeyword,
       Token staticKeyword, TypeName returnType, SimpleIdentifier name,
       FormalParameterList parameters) {
     FunctionBody body = _parseFunctionBody(
         externalKeyword != null || staticKeyword == null,
         ParserErrorCode.MISSING_FUNCTION_BODY, false);
     if (externalKeyword != null) {
       if (body is! EmptyFunctionBody) {
         _reportErrorForNode(ParserErrorCode.EXTERNAL_METHOD_WITH_BODY, body);
       }
     } else if (staticKeyword != null) {
       if (body is EmptyFunctionBody) {
         _reportErrorForNode(ParserErrorCode.ABSTRACT_STATIC_METHOD, body);
       }
     }
     return new MethodDeclaration(commentAndMetadata.comment,
         commentAndMetadata.metadata, externalKeyword, staticKeyword, returnType,
         null, null, name, parameters, body);
   }
 
   /**
-   * Parse a method declaration.
+   * Parse a method declaration. The [commentAndMetadata] is the documentation
+   * comment and metadata to be associated with the declaration. The
+   * [externalKeyword] is the 'external' token. The [staticKeyword] is the
+   * static keyword, or `null` if the getter is not static. The [returnType] is
+   * the return type of the method. Return the method declaration that was
+   * parsed.
    *
-   * <pre>
-   * functionDeclaration ::=
-   *     'external'? 'static'? functionSignature functionBody
-   *   | 'external'? functionSignature ';'
-   * </pre>
-   *
-   * @param commentAndMetadata the documentation comment and metadata to be associated with the
-   *          declaration
-   * @param externalKeyword the 'external' token
-   * @param staticKeyword the static keyword, or `null` if the getter is not static
-   * @param returnType the return type of the method
-   * @return the method declaration that was parsed
+   *     functionDeclaration ::=
+   *         'external'? 'static'? functionSignature functionBody
+   *       | 'external'? functionSignature ';'
    */
   MethodDeclaration _parseMethodDeclarationAfterReturnType(
       CommentAndMetadata commentAndMetadata, Token externalKeyword,
       Token staticKeyword, TypeName returnType) {
     SimpleIdentifier methodName = parseSimpleIdentifier();
     FormalParameterList parameters;
     if (!_matches(TokenType.OPEN_PAREN) &&
         (_matches(TokenType.OPEN_CURLY_BRACKET) ||
             _matches(TokenType.FUNCTION))) {
       _reportErrorForToken(
           ParserErrorCode.MISSING_METHOD_PARAMETERS, _currentToken.previous);
       parameters = new FormalParameterList(
           _createSyntheticToken(TokenType.OPEN_PAREN), null, null, null,
           _createSyntheticToken(TokenType.CLOSE_PAREN));
     } else {
       parameters = parseFormalParameterList();
     }
     _validateFormalParameterList(parameters);
     return _parseMethodDeclarationAfterParameters(commentAndMetadata,
         externalKeyword, staticKeyword, returnType, methodName, parameters);
   }
 
   /**
-   * Parse the modifiers preceding a declaration. This method allows the modifiers to appear in any
-   * order but does generate errors for duplicated modifiers. Checks for other problems, such as
-   * having the modifiers appear in the wrong order or specifying both 'const' and 'final', are
-   * reported in one of the methods whose name is prefixed with `validateModifiersFor`.
+   * Parse the modifiers preceding a declaration. This method allows the
+   * modifiers to appear in any order but does generate errors for duplicated
+   * modifiers. Checks for other problems, such as having the modifiers appear
+   * in the wrong order or specifying both 'const' and 'final', are reported in
+   * one of the methods whose name is prefixed with `validateModifiersFor`.
+   * Return the modifiers that were parsed.
    *
-   * <pre>
-   * modifiers ::=
-   *     ('abstract' | 'const' | 'external' | 'factory' | 'final' | 'static' | 'var')*
-   * </pre>
-   *
-   * @return the modifiers that were parsed
+   *     modifiers ::=
+   *         ('abstract' | 'const' | 'external' | 'factory' | 'final' | 'static' | 'var')*
    */
   Modifiers _parseModifiers() {
     Modifiers modifiers = new Modifiers();
     bool progress = true;
     while (progress) {
       if (_tokenMatches(_peek(), TokenType.PERIOD) ||
           _tokenMatches(_peek(), TokenType.LT) ||
           _tokenMatches(_peek(), TokenType.OPEN_PAREN)) {
         return modifiers;
       }
@@ skipping 60 matching lines @@
           modifiers.varKeyword = getAndAdvance();
         }
       } else {
         progress = false;
       }
     }
     return modifiers;
   }
 
   /**
-   * Parse a multiplicative expression.
+   * Parse a multiplicative expression. Return the multiplicative expression
+   * that was parsed.
    *
-   * <pre>
-   * multiplicativeExpression ::=
-   *     unaryExpression (multiplicativeOperator unaryExpression)*
-   *   | 'super' (multiplicativeOperator unaryExpression)+
-   * </pre>
-   *
-   * @return the multiplicative expression that was parsed
+   *     multiplicativeExpression ::=
+   *         unaryExpression (multiplicativeOperator unaryExpression)*
+   *       | 'super' (multiplicativeOperator unaryExpression)+
    */
   Expression _parseMultiplicativeExpression() {
     Expression expression;
     if (_matchesKeyword(Keyword.SUPER) &&
         _currentToken.next.type.isMultiplicativeOperator) {
       expression = new SuperExpression(getAndAdvance());
     } else {
       expression = _parseUnaryExpression();
     }
     while (_currentToken.type.isMultiplicativeOperator) {
       Token operator = getAndAdvance();
       expression =
           new BinaryExpression(expression, operator, _parseUnaryExpression());
     }
     return expression;
   }
 
   /**
-   * Parse a class native clause.
+   * Parse a class native clause. Return the native clause that was parsed.
    *
-   * <pre>
-   * classNativeClause ::=
-   *     'native' name
-   * </pre>
-   *
-   * @return the class native clause that was parsed
+   *     classNativeClause ::=
+   *         'native' name
    */
   NativeClause _parseNativeClause() {
     Token keyword = getAndAdvance();
     StringLiteral name = parseStringLiteral();
     return new NativeClause(keyword, name);
   }
 
   /**
-   * Parse a new expression.
+   * Parse a new expression. Return the new expression that was parsed.
    *
-   * <pre>
-   * newExpression ::=
-   *     instanceCreationExpression
-   * </pre>
-   *
-   * @return the new expression that was parsed
+   *     newExpression ::=
+   *         instanceCreationExpression
    */
   InstanceCreationExpression _parseNewExpression() =>
       _parseInstanceCreationExpression(_expectKeyword(Keyword.NEW));
 
   /**
-   * Parse a non-labeled statement.
+   * Parse a non-labeled statement. Return the non-labeled statement that was
+   * parsed.
    *
-   * <pre>
-   * nonLabeledStatement ::=
-   *     block
-   *   | assertStatement
-   *   | breakStatement
-   *   | continueStatement
-   *   | doStatement
-   *   | forStatement
-   *   | ifStatement
-   *   | returnStatement
-   *   | switchStatement
-   *   | tryStatement
-   *   | whileStatement
-   *   | variableDeclarationList ';'
-   *   | expressionStatement
-   *   | functionSignature functionBody
-   * </pre>
-   *
-   * @return the non-labeled statement that was parsed
+   *     nonLabeledStatement ::=
+   *         block
+   *       | assertStatement
+   *       | breakStatement
+   *       | continueStatement
+   *       | doStatement
+   *       | forStatement
+   *       | ifStatement
+   *       | returnStatement
+   *       | switchStatement
+   *       | tryStatement
+   *       | whileStatement
+   *       | variableDeclarationList ';'
+   *       | expressionStatement
+   *       | functionSignature functionBody
    */
   Statement _parseNonLabeledStatement() {
     // TODO(brianwilkerson) Pass the comment and metadata on where appropriate.
     CommentAndMetadata commentAndMetadata = _parseCommentAndMetadata();
     if (_matches(TokenType.OPEN_CURLY_BRACKET)) {
       if (_tokenMatches(_peek(), TokenType.STRING)) {
         Token afterString = _skipStringLiteral(_currentToken.next);
         if (afterString != null && afterString.type == TokenType.COLON) {
           return new ExpressionStatement(
               parseExpression2(), _expect(TokenType.SEMICOLON));
@@ skipping 135 matching lines @@
     } else if (_matches(TokenType.CLOSE_CURLY_BRACKET)) {
       _reportErrorForCurrentToken(ParserErrorCode.MISSING_STATEMENT);
       return new EmptyStatement(_createSyntheticToken(TokenType.SEMICOLON));
     } else {
       return new ExpressionStatement(
           parseExpression2(), _expect(TokenType.SEMICOLON));
     }
   }
 
   /**
-   * Parse an operator declaration.
+   * Parse an operator declaration. The [commentAndMetadata] is the
+   * documentation comment and metadata to be associated with the declaration.
+   * The [externalKeyword] is the 'external' token. The [returnType] is the
+   * return type that has already been parsed, or `null` if there was no return
+   * type. Return the operator declaration that was parsed.
    *
-   * <pre>
-   * operatorDeclaration ::=
-   *     operatorSignature (';' | functionBody)
+   *     operatorDeclaration ::=
+   *         operatorSignature (';' | functionBody)
    *
-   * operatorSignature ::=
-   *     'external'? returnType? 'operator' operator formalParameterList
-   * </pre>
-   *
-   * @param commentAndMetadata the documentation comment and metadata to be associated with the
-   *          declaration
-   * @param externalKeyword the 'external' token
-   * @param the return type that has already been parsed, or `null` if there was no return
-   *          type
-   * @return the operator declaration that was parsed
+   *     operatorSignature ::=
+   *         'external'? returnType? 'operator' operator formalParameterList
    */
   MethodDeclaration _parseOperator(CommentAndMetadata commentAndMetadata,
       Token externalKeyword, TypeName returnType) {
     Token operatorKeyword;
     if (_matchesKeyword(Keyword.OPERATOR)) {
       operatorKeyword = getAndAdvance();
     } else {
       _reportErrorForToken(
           ParserErrorCode.MISSING_KEYWORD_OPERATOR, _currentToken);
       operatorKeyword = _createSyntheticKeyword(Keyword.OPERATOR);
@@ skipping 20 matching lines @@
         _parseFunctionBody(true, ParserErrorCode.MISSING_FUNCTION_BODY, false);
     if (externalKeyword != null && body is! EmptyFunctionBody) {
       _reportErrorForCurrentToken(ParserErrorCode.EXTERNAL_OPERATOR_WITH_BODY);
     }
     return new MethodDeclaration(commentAndMetadata.comment,
         commentAndMetadata.metadata, externalKeyword, null, returnType, null,
         operatorKeyword, name, parameters, body);
   }
 
   /**
-   * Parse a return type if one is given, otherwise return `null` without advancing.
-   *
-   * @return the return type that was parsed
+   * Parse a return type if one is given, otherwise return `null` without
+   * advancing. Return the return type that was parsed.
    */
   TypeName _parseOptionalReturnType() {
     if (_matchesKeyword(Keyword.VOID)) {
       return parseReturnType();
     } else if (_matchesIdentifier() &&
         !_matchesKeyword(Keyword.GET) &&
         !_matchesKeyword(Keyword.SET) &&
         !_matchesKeyword(Keyword.OPERATOR) &&
         (_tokenMatchesIdentifier(_peek()) ||
             _tokenMatches(_peek(), TokenType.LT))) {
       return parseReturnType();
     } else if (_matchesIdentifier() &&
         _tokenMatches(_peek(), TokenType.PERIOD) &&
         _tokenMatchesIdentifier(_peekAt(2)) &&
         (_tokenMatchesIdentifier(_peekAt(3)) ||
             _tokenMatches(_peekAt(3), TokenType.LT))) {
       return parseReturnType();
     }
     return null;
   }
 
   /**
-   * Parse a part or part-of directive.
+   * Parse a part or part-of directive. The [commentAndMetadata] is the metadata
+   * to be associated with the directive. Return the part or part-of directive
+   * that was parsed.
    *
-   * <pre>
-   * partDirective ::=
-   *     metadata 'part' stringLiteral ';'
+   *     partDirective ::=
+   *         metadata 'part' stringLiteral ';'
    *
-   * partOfDirective ::=
-   *     metadata 'part' 'of' identifier ';'
-   * </pre>
-   *
-   * @param commentAndMetadata the metadata to be associated with the directive
-   * @return the part or part-of directive that was parsed
+   *     partOfDirective ::=
+   *         metadata 'part' 'of' identifier ';'
    */
   Directive _parsePartDirective(CommentAndMetadata commentAndMetadata) {
     Token partKeyword = _expectKeyword(Keyword.PART);
     if (_matchesString(_OF)) {
       Token ofKeyword = getAndAdvance();
       LibraryIdentifier libraryName = _parseLibraryName(
           ParserErrorCode.MISSING_NAME_IN_PART_OF_DIRECTIVE, ofKeyword);
       Token semicolon = _expect(TokenType.SEMICOLON);
       return new PartOfDirective(commentAndMetadata.comment,
           commentAndMetadata.metadata, partKeyword, ofKeyword, libraryName,
           semicolon);
     }
     StringLiteral partUri = _parseUri();
     Token semicolon = _expect(TokenType.SEMICOLON);
     return new PartDirective(commentAndMetadata.comment,
         commentAndMetadata.metadata, partKeyword, partUri, semicolon);
   }
 
   /**
-   * Parse a postfix expression.
+   * Parse a postfix expression. Return the postfix expression that was parsed.
    *
-   * <pre>
-   * postfixExpression ::=
-   *     assignableExpression postfixOperator
-   *   | primary selector*
+   *     postfixExpression ::=
+   *         assignableExpression postfixOperator
+   *       | primary selector*
    *
-   * selector ::=
-   *     assignableSelector
-   *   | argumentList
-   * </pre>
-   *
-   * @return the postfix expression that was parsed
+   *     selector ::=
+   *         assignableSelector
+   *       | argumentList
    */
   Expression _parsePostfixExpression() {
     Expression operand = _parseAssignableExpression(true);
     if (_matches(TokenType.OPEN_SQUARE_BRACKET) ||
         _matches(TokenType.PERIOD) ||
         _matches(TokenType.OPEN_PAREN)) {
       do {
         if (_matches(TokenType.OPEN_PAREN)) {
           ArgumentList argumentList = parseArgumentList();
           if (operand is PropertyAccess) {
@@ skipping 13 matching lines @@
     }
     if (!_currentToken.type.isIncrementOperator) {
       return operand;
     }
     _ensureAssignable(operand);
     Token operator = getAndAdvance();
     return new PostfixExpression(operand, operator);
   }
 
   /**
-   * Parse a primary expression.
+   * Parse a primary expression. Return the primary expression that was parsed.
    *
-   * <pre>
-   * primary ::=
-   *     thisExpression
-   *   | 'super' assignableSelector
-   *   | functionExpression
-   *   | literal
-   *   | identifier
-   *   | newExpression
-   *   | constObjectExpression
-   *   | '(' expression ')'
-   *   | argumentDefinitionTest
+   *     primary ::=
+   *         thisExpression
+   *       | 'super' assignableSelector
+   *       | functionExpression
+   *       | literal
+   *       | identifier
+   *       | newExpression
+   *       | constObjectExpression
+   *       | '(' expression ')'
+   *       | argumentDefinitionTest
    *
-   * literal ::=
-   *     nullLiteral
-   *   | booleanLiteral
-   *   | numericLiteral
-   *   | stringLiteral
-   *   | symbolLiteral
-   *   | mapLiteral
-   *   | listLiteral
-   * </pre>
-   *
-   * @return the primary expression that was parsed
+   *     literal ::=
+   *         nullLiteral
+   *       | booleanLiteral
+   *       | numericLiteral
+   *       | stringLiteral
+   *       | symbolLiteral
+   *       | mapLiteral
+   *       | listLiteral
    */
   Expression _parsePrimaryExpression() {
     if (_matchesKeyword(Keyword.THIS)) {
       return new ThisExpression(getAndAdvance());
     } else if (_matchesKeyword(Keyword.SUPER)) {
       return _parseAssignableSelector(
           new SuperExpression(getAndAdvance()), false);
     } else if (_matchesKeyword(Keyword.NULL)) {
       return new NullLiteral(getAndAdvance());
     } else if (_matchesKeyword(Keyword.FALSE)) {
@@ skipping 86 matching lines @@
       return _parsePrimaryExpression();
     } else if (_matches(TokenType.HASH)) {
       return _parseSymbolLiteral();
     } else {
       _reportErrorForCurrentToken(ParserErrorCode.MISSING_IDENTIFIER);
       return _createSyntheticIdentifier();
     }
   }
 
   /**
-   * Parse a redirecting constructor invocation.
+   * Parse a redirecting constructor invocation. Return the redirecting
+   * constructor invocation that was parsed.
    *
-   * <pre>
-   * redirectingConstructorInvocation ::=
-   *     'this' ('.' identifier)? arguments
-   * </pre>
-   *
-   * @return the redirecting constructor invocation that was parsed
+   *     redirectingConstructorInvocation ::=
+   *         'this' ('.' identifier)? arguments
    */
   RedirectingConstructorInvocation _parseRedirectingConstructorInvocation() {
     Token keyword = _expectKeyword(Keyword.THIS);
     Token period = null;
     SimpleIdentifier constructorName = null;
     if (_matches(TokenType.PERIOD)) {
       period = getAndAdvance();
       constructorName = parseSimpleIdentifier();
     }
     ArgumentList argumentList = parseArgumentList();
     return new RedirectingConstructorInvocation(
         keyword, period, constructorName, argumentList);
   }
 
   /**
-   * Parse a relational expression.
+   * Parse a relational expression. Return the relational expression that was
+   * parsed.
    *
-   * <pre>
-   * relationalExpression ::=
-   *     bitwiseOrExpression ('is' '!'? type | 'as' type | relationalOperator bitwiseOrExpression)?
-   *   | 'super' relationalOperator bitwiseOrExpression
-   * </pre>
-   *
-   * @return the relational expression that was parsed
+   *     relationalExpression ::=
+   *         bitwiseOrExpression ('is' '!'? type | 'as' type | relationalOperator bitwiseOrExpression)?
+   *       | 'super' relationalOperator bitwiseOrExpression
    */
   Expression _parseRelationalExpression() {
     if (_matchesKeyword(Keyword.SUPER) &&
         _currentToken.next.type.isRelationalOperator) {
       Expression expression = new SuperExpression(getAndAdvance());
       Token operator = getAndAdvance();
       expression = new BinaryExpression(
           expression, operator, parseBitwiseOrExpression());
       return expression;
     }
@@ skipping 11 matching lines @@
           expression, isOperator, notOperator, parseTypeName());
     } else if (_currentToken.type.isRelationalOperator) {
       Token operator = getAndAdvance();
       expression = new BinaryExpression(
           expression, operator, parseBitwiseOrExpression());
     }
     return expression;
   }
 
   /**
-   * Parse a rethrow expression.
+   * Parse a rethrow expression. Return the rethrow expression that was parsed.
    *
-   * <pre>
-   * rethrowExpression ::=
-   *     'rethrow'
-   * </pre>
-   *
-   * @return the rethrow expression that was parsed
+   *     rethrowExpression ::=
+   *         'rethrow'
    */
   Expression _parseRethrowExpression() =>
       new RethrowExpression(_expectKeyword(Keyword.RETHROW));
 
   /**
-   * Parse a return statement.
+   * Parse a return statement. Return the return statement that was parsed.
    *
-   * <pre>
-   * returnStatement ::=
-   *     'return' expression? ';'
-   * </pre>
-   *
-   * @return the return statement that was parsed
+   *     returnStatement ::=
+   *         'return' expression? ';'
    */
   Statement _parseReturnStatement() {
     Token returnKeyword = _expectKeyword(Keyword.RETURN);
     if (_matches(TokenType.SEMICOLON)) {
       return new ReturnStatement(returnKeyword, null, getAndAdvance());
     }
     Expression expression = parseExpression2();
     Token semicolon = _expect(TokenType.SEMICOLON);
     return new ReturnStatement(returnKeyword, expression, semicolon);
   }
 
   /**
-   * Parse a setter.
+   * Parse a setter. The [commentAndMetadata] is the documentation comment and
+   * metadata to be associated with the declaration. The [externalKeyword] is
+   * the 'external' token. The [staticKeyword] is the static keyword, or `null`
+   * if the setter is not static. The [returnType] is the return type that has
+   * already been parsed, or `null` if there was no return type. Return the
+   * setter that was parsed.
    *
-   * <pre>
-   * setter ::=
-   *     setterSignature functionBody?
+   *     setter ::=
+   *         setterSignature functionBody?
    *
-   * setterSignature ::=
-   *     'external'? 'static'? returnType? 'set' identifier formalParameterList
-   * </pre>
-   *
-   * @param commentAndMetadata the documentation comment and metadata to be associated with the
-   *          declaration
-   * @param externalKeyword the 'external' token
-   * @param staticKeyword the static keyword, or `null` if the setter is not static
-   * @param the return type that has already been parsed, or `null` if there was no return
-   *          type
-   * @return the setter that was parsed
+   *     setterSignature ::=
+   *         'external'? 'static'? returnType? 'set' identifier formalParameterList
    */
   MethodDeclaration _parseSetter(CommentAndMetadata commentAndMetadata,
       Token externalKeyword, Token staticKeyword, TypeName returnType) {
     Token propertyKeyword = _expectKeyword(Keyword.SET);
     SimpleIdentifier name = parseSimpleIdentifier();
     FormalParameterList parameters = parseFormalParameterList();
     _validateFormalParameterList(parameters);
     FunctionBody body = _parseFunctionBody(
         externalKeyword != null || staticKeyword == null,
         ParserErrorCode.STATIC_SETTER_WITHOUT_BODY, false);
     if (externalKeyword != null && body is! EmptyFunctionBody) {
       _reportErrorForCurrentToken(ParserErrorCode.EXTERNAL_SETTER_WITH_BODY);
     }
     return new MethodDeclaration(commentAndMetadata.comment,
         commentAndMetadata.metadata, externalKeyword, staticKeyword, returnType,
         propertyKeyword, null, name, parameters, body);
   }
 
   /**
-   * Parse a shift expression.
+   * Parse a shift expression. Return the shift expression that was parsed.
    *
-   * <pre>
-   * shiftExpression ::=
-   *     additiveExpression (shiftOperator additiveExpression)*
-   *   | 'super' (shiftOperator additiveExpression)+
-   * </pre>
-   *
-   * @return the shift expression that was parsed
+   *     shiftExpression ::=
+   *         additiveExpression (shiftOperator additiveExpression)*
+   *       | 'super' (shiftOperator additiveExpression)+
    */
   Expression _parseShiftExpression() {
     Expression expression;
     if (_matchesKeyword(Keyword.SUPER) &&
         _currentToken.next.type.isShiftOperator) {
       expression = new SuperExpression(getAndAdvance());
     } else {
       expression = _parseAdditiveExpression();
     }
     while (_currentToken.type.isShiftOperator) {
       Token operator = getAndAdvance();
       expression = new BinaryExpression(
           expression, operator, _parseAdditiveExpression());
     }
     return expression;
   }
 
   /**
-   * Parse a list of statements within a switch statement.
+   * Parse a list of statements within a switch statement. Return the statements
+   * that were parsed.
    *
-   * <pre>
-   * statements ::=
-   *     statement*
-   * </pre>
-   *
-   * @return the statements that were parsed
+   *     statements ::=
+   *         statement*
    */
   List<Statement> _parseStatementList() {
     List<Statement> statements = new List<Statement>();
     Token statementStart = _currentToken;
     while (!_matches(TokenType.EOF) &&
         !_matches(TokenType.CLOSE_CURLY_BRACKET) &&
         !_isSwitchMember()) {
       statements.add(parseStatement2());
       if (identical(_currentToken, statementStart)) {
         _reportErrorForToken(ParserErrorCode.UNEXPECTED_TOKEN, _currentToken, [
           _currentToken.lexeme
         ]);
         _advance();
       }
       statementStart = _currentToken;
     }
     return statements;
   }
 
   /**
-   * Parse a string literal that contains interpolations.
-   *
-   * @return the string literal that was parsed
+   * Parse a string literal that contains interpolations. Return the string
+   * literal that was parsed.
    */
   StringInterpolation _parseStringInterpolation(Token string) {
     List<InterpolationElement> elements = new List<InterpolationElement>();
     bool hasMore = _matches(TokenType.STRING_INTERPOLATION_EXPRESSION) ||
         _matches(TokenType.STRING_INTERPOLATION_IDENTIFIER);
     elements.add(new InterpolationString(
         string, _computeStringValue(string.lexeme, true, !hasMore)));
     while (hasMore) {
       if (_matches(TokenType.STRING_INTERPOLATION_EXPRESSION)) {
         Token openToken = getAndAdvance();
@@ skipping 24 matching lines @@
         elements.add(new InterpolationString(
             string, _computeStringValue(string.lexeme, false, !hasMore)));
       } else {
         hasMore = false;
       }
     }
     return new StringInterpolation(elements);
   }
 
   /**
-   * Parse a super constructor invocation.
+   * Parse a super constructor invocation. Return the super constructor
+   * invocation that was parsed.
    *
-   * <pre>
-   * superConstructorInvocation ::=
-   *     'super' ('.' identifier)? arguments
-   * </pre>
-   *
-   * @return the super constructor invocation that was parsed
+   *     superConstructorInvocation ::=
+   *         'super' ('.' identifier)? arguments
    */
   SuperConstructorInvocation _parseSuperConstructorInvocation() {
     Token keyword = _expectKeyword(Keyword.SUPER);
     Token period = null;
     SimpleIdentifier constructorName = null;
     if (_matches(TokenType.PERIOD)) {
       period = getAndAdvance();
       constructorName = parseSimpleIdentifier();
     }
     ArgumentList argumentList = parseArgumentList();
     return new SuperConstructorInvocation(
         keyword, period, constructorName, argumentList);
   }
 
   /**
-   * Parse a switch statement.
+   * Parse a switch statement. Return the switch statement that was parsed.
    *
-   * <pre>
-   * switchStatement ::=
-   *     'switch' '(' expression ')' '{' switchCase* defaultCase? '}'
+   *     switchStatement ::=
+   *         'switch' '(' expression ')' '{' switchCase* defaultCase? '}'
    *
-   * switchCase ::=
-   *     label* ('case' expression ':') statements
+   *     switchCase ::=
+   *         label* ('case' expression ':') statements
    *
-   * defaultCase ::=
-   *     label* 'default' ':' statements
-   * </pre>
-   *
-   * @return the switch statement that was parsed
+   *     defaultCase ::=
+   *         label* 'default' ':' statements
    */
   SwitchStatement _parseSwitchStatement() {
     bool wasInSwitch = _inSwitch;
     _inSwitch = true;
     try {
       HashSet<String> definedLabels = new HashSet<String>();
       Token keyword = _expectKeyword(Keyword.SWITCH);
       Token leftParenthesis = _expect(TokenType.OPEN_PAREN);
       Expression expression = parseExpression2();
       Token rightParenthesis = _expect(TokenType.CLOSE_PAREN);
@@ skipping 51 matching lines @@
       }
       Token rightBracket = _expect(TokenType.CLOSE_CURLY_BRACKET);
       return new SwitchStatement(keyword, leftParenthesis, expression,
           rightParenthesis, leftBracket, members, rightBracket);
     } finally {
       _inSwitch = wasInSwitch;
     }
   }
 
   /**
-   * Parse a symbol literal.
+   * Parse a symbol literal. Return the symbol literal that was parsed.
    *
-   * <pre>
-   * symbolLiteral ::=
-   *     '#' identifier ('.' identifier)*
-   * </pre>
-   *
-   * @return the symbol literal that was parsed
+   *     symbolLiteral ::=
+   *         '#' identifier ('.' identifier)*
    */
   SymbolLiteral _parseSymbolLiteral() {
     Token poundSign = getAndAdvance();
     List<Token> components = new List<Token>();
     if (_matchesIdentifier()) {
       components.add(getAndAdvance());
       while (_matches(TokenType.PERIOD)) {
         _advance();
         if (_matchesIdentifier()) {
           components.add(getAndAdvance());
         } else {
           _reportErrorForCurrentToken(ParserErrorCode.MISSING_IDENTIFIER);
           components.add(_createSyntheticToken(TokenType.IDENTIFIER));
           break;
         }
       }
     } else if (_currentToken.isOperator) {
       components.add(getAndAdvance());
     } else if (_tokenMatchesKeyword(_currentToken, Keyword.VOID)) {
       components.add(getAndAdvance());
     } else {
       _reportErrorForCurrentToken(ParserErrorCode.MISSING_IDENTIFIER);
       components.add(_createSyntheticToken(TokenType.IDENTIFIER));
     }
     return new SymbolLiteral(poundSign, components);
   }
 
   /**
-   * Parse a throw expression.
+   * Parse a throw expression. Return the throw expression that was parsed.
    *
-   * <pre>
-   * throwExpression ::=
-   *     'throw' expression
-   * </pre>
-   *
-   * @return the throw expression that was parsed
+   *     throwExpression ::=
+   *         'throw' expression
    */
   Expression _parseThrowExpression() {
     Token keyword = _expectKeyword(Keyword.THROW);
     if (_matches(TokenType.SEMICOLON) || _matches(TokenType.CLOSE_PAREN)) {
       _reportErrorForToken(
           ParserErrorCode.MISSING_EXPRESSION_IN_THROW, _currentToken);
       return new ThrowExpression(keyword, _createSyntheticIdentifier());
     }
     Expression expression = parseExpression2();
     return new ThrowExpression(keyword, expression);
   }
 
   /**
-   * Parse a throw expression.
+   * Parse a throw expression. Return the throw expression that was parsed.
    *
-   * <pre>
-   * throwExpressionWithoutCascade ::=
-   *     'throw' expressionWithoutCascade
-   * </pre>
-   *
-   * @return the throw expression that was parsed
+   *     throwExpressionWithoutCascade ::=
+   *         'throw' expressionWithoutCascade
    */
   Expression _parseThrowExpressionWithoutCascade() {
     Token keyword = _expectKeyword(Keyword.THROW);
     if (_matches(TokenType.SEMICOLON) || _matches(TokenType.CLOSE_PAREN)) {
       _reportErrorForToken(
           ParserErrorCode.MISSING_EXPRESSION_IN_THROW, _currentToken);
       return new ThrowExpression(keyword, _createSyntheticIdentifier());
     }
     Expression expression = parseExpressionWithoutCascade();
     return new ThrowExpression(keyword, expression);
   }
 
   /**
-   * Parse a try statement.
+   * Parse a try statement. Return the try statement that was parsed.
    *
-   * <pre>
-   * tryStatement ::=
-   *     'try' block (onPart+ finallyPart? | finallyPart)
+   *     tryStatement ::=
+   *         'try' block (onPart+ finallyPart? | finallyPart)
    *
-   * onPart ::=
-   *     catchPart block
-   *   | 'on' type catchPart? block
+   *     onPart ::=
+   *         catchPart block
+   *       | 'on' type catchPart? block
    *
-   * catchPart ::=
-   *     'catch' '(' identifier (',' identifier)? ')'
+   *     catchPart ::=
+   *         'catch' '(' identifier (',' identifier)? ')'
    *
-   * finallyPart ::=
-   *     'finally' block
-   * </pre>
-   *
-   * @return the try statement that was parsed
+   *     finallyPart ::=
+   *         'finally' block
    */
   Statement _parseTryStatement() {
     Token tryKeyword = _expectKeyword(Keyword.TRY);
     Block body = parseBlock();
     List<CatchClause> catchClauses = new List<CatchClause>();
     Block finallyClause = null;
     while (_matchesString(_ON) || _matchesKeyword(Keyword.CATCH)) {
       Token onKeyword = null;
       TypeName exceptionType = null;
       if (_matchesString(_ON)) {
@@ skipping 28 matching lines @@
     } else {
       if (catchClauses.isEmpty) {
         _reportErrorForCurrentToken(ParserErrorCode.MISSING_CATCH_OR_FINALLY);
       }
     }
     return new TryStatement(
         tryKeyword, body, catchClauses, finallyKeyword, finallyClause);
   }
 
   /**
-   * Parse a type alias.
+   * Parse a type alias. The [commentAndMetadata] is the metadata to be
+   * associated with the member. Return the type alias that was parsed.
    *
-   * <pre>
-   * typeAlias ::=
-   *     'typedef' typeAliasBody
+   *     typeAlias ::=
+   *         'typedef' typeAliasBody
    *
-   * typeAliasBody ::=
-   *     classTypeAlias
-   *   | functionTypeAlias
+   *     typeAliasBody ::=
+   *         classTypeAlias
+   *       | functionTypeAlias
    *
-   * classTypeAlias ::=
-   *     identifier typeParameters? '=' 'abstract'? mixinApplication
+   *     classTypeAlias ::=
+   *         identifier typeParameters? '=' 'abstract'? mixinApplication
    *
-   * mixinApplication ::=
-   *     qualified withClause implementsClause? ';'
+   *     mixinApplication ::=
+   *         qualified withClause implementsClause? ';'
    *
-   * functionTypeAlias ::=
-   *     functionPrefix typeParameterList? formalParameterList ';'
+   *     functionTypeAlias ::=
+   *         functionPrefix typeParameterList? formalParameterList ';'
    *
-   * functionPrefix ::=
-   *     returnType? name
-   * </pre>
-   *
-   * @param commentAndMetadata the metadata to be associated with the member
-   * @return the type alias that was parsed
+   *     functionPrefix ::=
+   *         returnType? name
    */
   TypeAlias _parseTypeAlias(CommentAndMetadata commentAndMetadata) {
     Token keyword = _expectKeyword(Keyword.TYPEDEF);
     if (_matchesIdentifier()) {
       Token next = _peek();
       if (_tokenMatches(next, TokenType.LT)) {
         next = _skipTypeParameterList(next);
         if (next != null && _tokenMatches(next, TokenType.EQ)) {
           TypeAlias typeAlias =
               _parseClassTypeAlias(commentAndMetadata, null, keyword);
           _reportErrorForToken(
               ParserErrorCode.DEPRECATED_CLASS_TYPE_ALIAS, keyword);
           return typeAlias;
         }
       } else if (_tokenMatches(next, TokenType.EQ)) {
         TypeAlias typeAlias =
             _parseClassTypeAlias(commentAndMetadata, null, keyword);
         _reportErrorForToken(
             ParserErrorCode.DEPRECATED_CLASS_TYPE_ALIAS, keyword);
         return typeAlias;
       }
     }
     return _parseFunctionTypeAlias(commentAndMetadata, keyword);
   }
 
   /**
-   * Parse a unary expression.
+   * Parse a unary expression. Return the unary expression that was parsed.
    *
-   * <pre>
-   * unaryExpression ::=
-   *     prefixOperator unaryExpression
-   *   | awaitExpression
-   *   | postfixExpression
-   *   | unaryOperator 'super'
-   *   | '-' 'super'
-   *   | incrementOperator assignableExpression
-   * </pre>
-   *
-   * @return the unary expression that was parsed
+   *     unaryExpression ::=
+   *         prefixOperator unaryExpression
+   *       | awaitExpression
+   *       | postfixExpression
+   *       | unaryOperator 'super'
+   *       | '-' 'super'
+   *       | incrementOperator assignableExpression
    */
   Expression _parseUnaryExpression() {
     if (_matches(TokenType.MINUS) ||
         _matches(TokenType.BANG) ||
         _matches(TokenType.TILDE)) {
       Token operator = getAndAdvance();
       if (_matchesKeyword(Keyword.SUPER)) {
         if (_tokenMatches(_peek(), TokenType.OPEN_SQUARE_BRACKET) ||
             _tokenMatches(_peek(), TokenType.PERIOD)) {
           //     "prefixOperator unaryExpression"
@@ skipping 42 matching lines @@
     } else if (_matches(TokenType.PLUS)) {
       _reportErrorForCurrentToken(ParserErrorCode.MISSING_IDENTIFIER);
       return _createSyntheticIdentifier();
     } else if (_inAsync && _matchesString(_AWAIT)) {
       return _parseAwaitExpression();
     }
     return _parsePostfixExpression();
   }
 
   /**
-   * Parse a string literal representing a URI.
+   * Parse a string literal representing a URI. Return the string literal that
+   * was parsed.
    */
   StringLiteral _parseUri() {
     bool iskeywordAfterUri(Token token) => token.lexeme == Keyword.AS.syntax ||
         token.lexeme == _HIDE ||
         token.lexeme == _SHOW;
     if (!_matches(TokenType.STRING) &&
         !_matches(TokenType.SEMICOLON) &&
         !iskeywordAfterUri(_currentToken)) {
       // Attempt to recover in the case where the URI was not enclosed in
       // quotes.
@@ skipping 29 matching lines @@
         _reportErrorForToken(
             ParserErrorCode.NON_STRING_LITERAL_AS_URI, newToken);
         _currentToken = endToken.next;
         return new SimpleStringLiteral(newToken, value);
       }
     }
     return parseStringLiteral();
   }
 
   /**
-   * Parse a variable declaration.
+   * Parse a variable declaration. Return the variable declaration that was
+   * parsed.
    *
-   * <pre>
-   * variableDeclaration ::=
-   *     identifier ('=' expression)?
-   * </pre>
-   *
-   * @return the variable declaration that was parsed
+   *     variableDeclaration ::=
+   *         identifier ('=' expression)?
    */
   VariableDeclaration _parseVariableDeclaration() {
     CommentAndMetadata commentAndMetadata = _parseCommentAndMetadata();
     SimpleIdentifier name = parseSimpleIdentifier();
     Token equals = null;
     Expression initializer = null;
     if (_matches(TokenType.EQ)) {
       equals = getAndAdvance();
       initializer = parseExpression2();
     }
     return new VariableDeclaration(commentAndMetadata.comment,
         commentAndMetadata.metadata, name, equals, initializer);
   }
 
   /**
-   * Parse a variable declaration list.
+   * Parse a variable declaration list. The [commentAndMetadata] is the metadata
+   * to be associated with the variable declaration list. Return the variable
+   * declaration list that was parsed.
    *
-   * <pre>
-   * variableDeclarationList ::=
-   *     finalConstVarOrType variableDeclaration (',' variableDeclaration)*
-   * </pre>
-   *
-   * @param commentAndMetadata the metadata to be associated with the variable declaration list
-   * @return the variable declaration list that was parsed
+   *     variableDeclarationList ::=
+   *         finalConstVarOrType variableDeclaration (',' variableDeclaration)*
    */
   VariableDeclarationList _parseVariableDeclarationListAfterMetadata(
       CommentAndMetadata commentAndMetadata) {
     FinalConstVarOrType holder = _parseFinalConstVarOrType(false);
     return _parseVariableDeclarationListAfterType(
         commentAndMetadata, holder.keyword, holder.type);
   }
 
   /**
-   * Parse a variable declaration list.
+   * Parse a variable declaration list. The [commentAndMetadata] is the metadata
+   * to be associated with the variable declaration list, or `null` if there is
+   * no attempt at parsing the comment and metadata. The [keyword] is the token
+   * representing the 'final', 'const' or 'var' keyword, or `null` if there is
+   * no keyword. The [type] is the type of the variables in the list. Return the
+   * variable declaration list that was parsed.
    *
-   * <pre>
-   * variableDeclarationList ::=
-   *     finalConstVarOrType variableDeclaration (',' variableDeclaration)*
-   * </pre>
-   *
-   * @param commentAndMetadata the metadata to be associated with the variable declaration list, or
-   *          `null` if there is no attempt at parsing the comment and metadata
-   * @param keyword the token representing the 'final', 'const' or 'var' keyword, or `null` if
-   *          there is no keyword
-   * @param type the type of the variables in the list
-   * @return the variable declaration list that was parsed
+   *     variableDeclarationList ::=
+   *         finalConstVarOrType variableDeclaration (',' variableDeclaration)*
    */
   VariableDeclarationList _parseVariableDeclarationListAfterType(
       CommentAndMetadata commentAndMetadata, Token keyword, TypeName type) {
     if (type != null &&
         keyword != null &&
         _tokenMatchesKeyword(keyword, Keyword.VAR)) {
       _reportErrorForToken(ParserErrorCode.VAR_AND_TYPE, keyword);
     }
     List<VariableDeclaration> variables = new List<VariableDeclaration>();
     variables.add(_parseVariableDeclaration());
     while (_matches(TokenType.COMMA)) {
       _advance();
       variables.add(_parseVariableDeclaration());
     }
     return new VariableDeclarationList(
         commentAndMetadata != null ? commentAndMetadata.comment : null,
         commentAndMetadata != null ? commentAndMetadata.metadata : null,
         keyword, type, variables);
   }
 
   /**
-   * Parse a variable declaration statement.
+   * Parse a variable declaration statement. The [commentAndMetadata] is the
+   * metadata to be associated with the variable declaration statement, or
+   * `null` if there is no attempt at parsing the comment and metadata. Return
+   * the variable declaration statement that was parsed.
    *
-   * <pre>
-   * variableDeclarationStatement ::=
-   *     variableDeclarationList ';'
-   * </pre>
-   *
-   * @param commentAndMetadata the metadata to be associated with the variable declaration
-   *          statement, or `null` if there is no attempt at parsing the comment and metadata
-   * @return the variable declaration statement that was parsed
+   *     variableDeclarationStatement ::=
+   *         variableDeclarationList ';'
    */
   VariableDeclarationStatement _parseVariableDeclarationStatementAfterMetadata(
       CommentAndMetadata commentAndMetadata) {
     //    Token startToken = currentToken;
     VariableDeclarationList variableList =
         _parseVariableDeclarationListAfterMetadata(commentAndMetadata);
 //        if (!matches(TokenType.SEMICOLON)) {
 //          if (matches(startToken, Keyword.VAR) && isTypedIdentifier(startToken.getNext())) {
 //            // TODO(brianwilkerson) This appears to be of the form "var type variable". We should do
 //            // a better job of recovering in this case.
 //          }
 //        }
     Token semicolon = _expect(TokenType.SEMICOLON);
     return new VariableDeclarationStatement(variableList, semicolon);
   }
 
   /**
-   * Parse a variable declaration statement.
+   * Parse a variable declaration statement. The [commentAndMetadata] is the
+   * metadata to be associated with the variable declaration statement, or
+   * `null` if there is no attempt at parsing the comment and metadata. The
+   * [keyword] is the token representing the 'final', 'const' or 'var' keyword,
+   * or `null` if there is no keyword. The [type] is the type of the variables
+   * in the list. Return the variable declaration statement that was parsed.
    *
-   * <pre>
-   * variableDeclarationStatement ::=
-   *     variableDeclarationList ';'
-   * </pre>
-   *
-   * @param commentAndMetadata the metadata to be associated with the variable declaration
-   *          statement, or `null` if there is no attempt at parsing the comment and metadata
-   * @param keyword the token representing the 'final', 'const' or 'var' keyword, or `null` if
-   *          there is no keyword
-   * @param type the type of the variables in the list
-   * @return the variable declaration statement that was parsed
+   *     variableDeclarationStatement ::=
+   *         variableDeclarationList ';'
    */
   VariableDeclarationStatement _parseVariableDeclarationStatementAfterType(
       CommentAndMetadata commentAndMetadata, Token keyword, TypeName type) {
     VariableDeclarationList variableList =
         _parseVariableDeclarationListAfterType(
             commentAndMetadata, keyword, type);
     Token semicolon = _expect(TokenType.SEMICOLON);
     return new VariableDeclarationStatement(variableList, semicolon);
   }
 
   /**
-   * Parse a while statement.
+   * Parse a while statement. Return the while statement that was parsed.
    *
-   * <pre>
-   * whileStatement ::=
-   *     'while' '(' expression ')' statement
-   * </pre>
-   *
-   * @return the while statement that was parsed
+   *     whileStatement ::=
+   *         'while' '(' expression ')' statement
    */
   Statement _parseWhileStatement() {
     bool wasInLoop = _inLoop;
     _inLoop = true;
     try {
       Token keyword = _expectKeyword(Keyword.WHILE);
       Token leftParenthesis = _expect(TokenType.OPEN_PAREN);
       Expression condition = parseExpression2();
       Token rightParenthesis = _expect(TokenType.CLOSE_PAREN);
       Statement body = parseStatement2();
       return new WhileStatement(
           keyword, leftParenthesis, condition, rightParenthesis, body);
     } finally {
       _inLoop = wasInLoop;
     }
   }
 
   /**
-   * Parse a yield statement.
+   * Parse a yield statement. Return the yield statement that was parsed.
    *
-   * <pre>
-   * yieldStatement ::=
-   *     'yield' '*'? expression ';'
-   * </pre>
-   *
-   * @return the yield statement that was parsed
+   *     yieldStatement ::=
+   *         'yield' '*'? expression ';'
    */
   YieldStatement _parseYieldStatement() {
     Token yieldToken = getAndAdvance();
     Token star = null;
     if (_matches(TokenType.STAR)) {
       star = getAndAdvance();
     }
     Expression expression = parseExpression2();
     Token semicolon = _expect(TokenType.SEMICOLON);
     return new YieldStatement(yieldToken, star, expression, semicolon);
   }
 
   /**
-   * Return the token that is immediately after the current token. This is equivalent to
-   * [peekAt].
-   *
-   * @return the token that is immediately after the current token
+   * Return the token that is immediately after the current token. This is
+   * equivalent to [_peekAt](1).
    */
   Token _peek() => _currentToken.next;
 
   /**
-   * Return the token that is the given distance after the current token.
-   *
-   * @param distance the number of tokens to look ahead, where `0` is the current token,
-   *          `1` is the next token, etc.
-   * @return the token that is the given distance after the current token
+   * Return the token that is the given [distance] after the current token,
+   * where the distance is the number of tokens to look ahead. A distance of `0`
+   * is the current token, `1` is the next token, etc.
    */
   Token _peekAt(int distance) {
     Token token = _currentToken;
     for (int i = 0; i < distance; i++) {
       token = token.next;
     }
     return token;
   }
 
   /**
-   * Report the given [AnalysisError].
-   *
-   * @param error the error to be reported
+   * Report the given [error].
    */
   void _reportError(AnalysisError error) {
     if (_errorListenerLock != 0) {
       return;
     }
     _errorListener.onError(error);
   }
 
   /**
-   * Report an error with the given error code and arguments.
-   *
-   * @param errorCode the error code of the error to be reported
-   * @param arguments the arguments to the error, used to compose the error message
+   * Report an error with the given [errorCode] and [arguments] associated with
+   * the current token.
    */
   void _reportErrorForCurrentToken(ParserErrorCode errorCode,
       [List<Object> arguments]) {
     _reportErrorForToken(errorCode, _currentToken, arguments);
   }
 
   /**
-   * Report an error with the given error code and arguments.
-   *
-   * @param errorCode the error code of the error to be reported
-   * @param node the node specifying the location of the error
-   * @param arguments the arguments to the error, used to compose the error message
+   * Report an error with the given [errorCode] and [arguments] associated with
+   * the given [node].
    */
   void _reportErrorForNode(ParserErrorCode errorCode, AstNode node,
       [List<Object> arguments]) {
     _reportError(new AnalysisError.con2(
         _source, node.offset, node.length, errorCode, arguments));
   }
 
   /**
-   * Report an error with the given error code and arguments.
-   *
-   * @param errorCode the error code of the error to be reported
-   * @param token the token specifying the location of the error
-   * @param arguments the arguments to the error, used to compose the error message
+   * Report an error with the given [errorCode] and [arguments] associated with
+   * the given [token].
    */
   void _reportErrorForToken(ErrorCode errorCode, Token token,
       [List<Object> arguments]) {
     if (token.type == TokenType.EOF) {
       token = token.previous;
     }
     _reportError(new AnalysisError.con2(_source, token.offset,
         math.max(token.length, 1), errorCode, arguments));
   }
 
   /**
    * Skips a block with all containing blocks.
    */
   void _skipBlock() {
     Token endToken = (_currentToken as BeginToken).endToken;
     if (endToken == null) {
       endToken = _currentToken.next;
       while (!identical(endToken, _currentToken)) {
         _currentToken = endToken;
         endToken = _currentToken.next;
       }
       _reportErrorForToken(
           ParserErrorCode.EXPECTED_TOKEN, _currentToken.previous, ["}"]);
     } else {
       _currentToken = endToken.next;
     }
   }
 
   /**
-   * Parse the 'final', 'const', 'var' or type preceding a variable declaration, starting at the
-   * given token, without actually creating a type or changing the current token. Return the token
-   * following the type that was parsed, or `null` if the given token is not the first token
-   * in a valid type.
+   * Parse the 'final', 'const', 'var' or type preceding a variable declaration,
+   * starting at the given token, without actually creating a type or changing
+   * the current token. Return the token following the type that was parsed, or
+   * `null` if the given token is not the first token in a valid type. The
+   * [startToken] is the token at which parsing is to begin. Return the token
+   * following the type that was parsed.
    *
-   * <pre>
    * finalConstVarOrType ::=
    *   | 'final' type?
    *   | 'const' type?
    *   | 'var'
    *   | type
-   * </pre>
-   *
-   * @param startToken the token at which parsing is to begin
-   * @return the token following the type that was parsed
    */
   Token _skipFinalConstVarOrType(Token startToken) {
     if (_tokenMatchesKeyword(startToken, Keyword.FINAL) ||
         _tokenMatchesKeyword(startToken, Keyword.CONST)) {
       Token next = startToken.next;
       if (_tokenMatchesIdentifier(next)) {
         Token next2 = next.next;
         // "Type parameter" or "Type<" or "prefix.Type"
         if (_tokenMatchesIdentifier(next2) ||
             _tokenMatches(next2, TokenType.LT) ||
@@ skipping 15 matching lines @@
               (_tokenMatchesIdentifier(next.next.next) ||
                   _tokenMatches(next.next.next, TokenType.LT) ||
                   _tokenMatchesKeyword(next.next.next, Keyword.THIS)))) {
         return _skipReturnType(startToken);
       }
     }
     return null;
   }
 
   /**
-   * Parse a list of formal parameters, starting at the given token, without actually creating a
-   * formal parameter list or changing the current token. Return the token following the formal
-   * parameter list that was parsed, or `null` if the given token is not the first token in a
-   * valid list of formal parameter.
+   * Parse a list of formal parameters, starting at the [startToken], without
+   * actually creating a formal parameter list or changing the current token.
+   * Return the token following the formal parameter list that was parsed, or
+   * `null` if the given token is not the first token in a valid list of formal
+   * parameter.
    *
-   * Note that unlike other skip methods, this method uses a heuristic. In the worst case, the
-   * parameters could be prefixed by metadata, which would require us to be able to skip arbitrary
-   * expressions. Rather than duplicate the logic of most of the parse methods we simply look for
-   * something that is likely to be a list of parameters and then skip to returning the token after
-   * the closing parenthesis.
+   * Note that unlike other skip methods, this method uses a heuristic. In the
+   * worst case, the parameters could be prefixed by metadata, which would
+   * require us to be able to skip arbitrary expressions. Rather than duplicate
+   * the logic of most of the parse methods we simply look for something that is
+   * likely to be a list of parameters and then skip to returning the token
+   * after the closing parenthesis.
    *
    * This method must be kept in sync with [parseFormalParameterList].
    *
-   * <pre>
-   * formalParameterList ::=
-   *     '(' ')'
-   *   | '(' normalFormalParameters (',' optionalFormalParameters)? ')'
-   *   | '(' optionalFormalParameters ')'
+   *     formalParameterList ::=
+   *         '(' ')'
+   *       | '(' normalFormalParameters (',' optionalFormalParameters)? ')'
+   *       | '(' optionalFormalParameters ')'
    *
-   * normalFormalParameters ::=
-   *     normalFormalParameter (',' normalFormalParameter)*
+   *     normalFormalParameters ::=
+   *         normalFormalParameter (',' normalFormalParameter)*
    *
-   * optionalFormalParameters ::=
-   *     optionalPositionalFormalParameters
-   *   | namedFormalParameters
+   *     optionalFormalParameters ::=
+   *         optionalPositionalFormalParameters
+   *       | namedFormalParameters
    *
-   * optionalPositionalFormalParameters ::=
-   *     '[' defaultFormalParameter (',' defaultFormalParameter)* ']'
+   *     optionalPositionalFormalParameters ::=
+   *         '[' defaultFormalParameter (',' defaultFormalParameter)* ']'
    *
-   * namedFormalParameters ::=
-   *     '{' defaultNamedParameter (',' defaultNamedParameter)* '}'
-   * </pre>
-   *
-   * @param startToken the token at which parsing is to begin
-   * @return the token following the formal parameter list that was parsed
+   *     namedFormalParameters ::=
+   *         '{' defaultNamedParameter (',' defaultNamedParameter)* '}'
    */
   Token _skipFormalParameterList(Token startToken) {
     if (!_tokenMatches(startToken, TokenType.OPEN_PAREN)) {
       return null;
     }
     Token next = startToken.next;
     if (_tokenMatches(next, TokenType.CLOSE_PAREN)) {
       return next.next;
     }
     //
@@ skipping 31 matching lines @@
     if (afterType == null) {
       return null;
     }
     if (_skipSimpleIdentifier(afterType) == null) {
       return null;
     }
     return _skipPastMatchingToken(startToken);
   }
 
   /**
-   * If the given token is a begin token with an associated end token, then return the token
-   * following the end token. Otherwise, return `null`.
-   *
-   * @param startToken the token that is assumed to be a being token
-   * @return the token following the matching end token
+   * If the [startToken] is a begin token with an associated end token, then
+   * return the token following the end token. Otherwise, return `null`.
    */
   Token _skipPastMatchingToken(Token startToken) {
     if (startToken is! BeginToken) {
       return null;
     }
     Token closeParen = (startToken as BeginToken).endToken;
     if (closeParen == null) {
       return null;
     }
     return closeParen.next;
   }
 
   /**
-   * Parse a prefixed identifier, starting at the given token, without actually creating a prefixed
-   * identifier or changing the current token. Return the token following the prefixed identifier
-   * that was parsed, or `null` if the given token is not the first token in a valid prefixed
-   * identifier.
+   * Parse a prefixed identifier, starting at the [startToken], without actually
+   * creating a prefixed identifier or changing the current token. Return the
+   * token following the prefixed identifier that was parsed, or `null` if the
+   * given token is not the first token in a valid prefixed identifier.
    *
    * This method must be kept in sync with [parsePrefixedIdentifier].
    *
-   * <pre>
-   * prefixedIdentifier ::=
-   *     identifier ('.' identifier)?
-   * </pre>
-   *
-   * @param startToken the token at which parsing is to begin
-   * @return the token following the prefixed identifier that was parsed
+   *     prefixedIdentifier ::=
+   *         identifier ('.' identifier)?
    */
   Token _skipPrefixedIdentifier(Token startToken) {
     Token token = _skipSimpleIdentifier(startToken);
     if (token == null) {
       return null;
     } else if (!_tokenMatches(token, TokenType.PERIOD)) {
       return token;
     }
     return _skipSimpleIdentifier(token.next);
   }
 
   /**
-   * Parse a return type, starting at the given token, without actually creating a return type or
-   * changing the current token. Return the token following the return type that was parsed, or
-   * `null` if the given token is not the first token in a valid return type.
+   * Parse a return type, starting at the [startToken], without actually
+   * creating a return type or changing the current token. Return the token
+   * following the return type that was parsed, or `null` if the given token is
+   * not the first token in a valid return type.
    *
    * This method must be kept in sync with [parseReturnType].
    *
-   * <pre>
-   * returnType ::=
-   *     'void'
-   *   | type
-   * </pre>
-   *
-   * @param startToken the token at which parsing is to begin
-   * @return the token following the return type that was parsed
+   *     returnType ::=
+   *         'void'
+   *       | type
    */
   Token _skipReturnType(Token startToken) {
     if (_tokenMatchesKeyword(startToken, Keyword.VOID)) {
       return startToken.next;
     } else {
       return _skipTypeName(startToken);
     }
   }
 
   /**
-   * Parse a simple identifier, starting at the given token, without actually creating a simple
-   * identifier or changing the current token. Return the token following the simple identifier that
-   * was parsed, or `null` if the given token is not the first token in a valid simple
-   * identifier.
+   * Parse a simple identifier, starting at the [startToken], without actually
+   * creating a simple identifier or changing the current token. Return the
+   * token following the simple identifier that was parsed, or `null` if the
+   * given token is not the first token in a valid simple identifier.
    *
    * This method must be kept in sync with [parseSimpleIdentifier].
    *
-   * <pre>
-   * identifier ::=
-   *     IDENTIFIER
-   * </pre>
-   *
-   * @param startToken the token at which parsing is to begin
-   * @return the token following the simple identifier that was parsed
+   *     identifier ::=
+   *         IDENTIFIER
    */
   Token _skipSimpleIdentifier(Token startToken) {
     if (_tokenMatches(startToken, TokenType.IDENTIFIER) ||
         (_tokenMatches(startToken, TokenType.KEYWORD) &&
             (startToken as KeywordToken).keyword.isPseudoKeyword)) {
       return startToken.next;
     }
     return null;
   }
 
   /**
-   * Parse a string literal that contains interpolations, starting at the given token, without
-   * actually creating a string literal or changing the current token. Return the token following
-   * the string literal that was parsed, or `null` if the given token is not the first token
-   * in a valid string literal.
+   * Parse a string literal that contains interpolations, starting at the
+   * [startToken], without actually creating a string literal or changing the
+   * current token. Return the token following the string literal that was
+   * parsed, or `null` if the given token is not the first token in a valid
+   * string literal.
    *
    * This method must be kept in sync with [parseStringInterpolation].
-   *
-   * @param startToken the token at which parsing is to begin
-   * @return the string literal that was parsed
    */
   Token _skipStringInterpolation(Token startToken) {
     Token token = startToken;
     TokenType type = token.type;
     while (type == TokenType.STRING_INTERPOLATION_EXPRESSION ||
         type == TokenType.STRING_INTERPOLATION_IDENTIFIER) {
       if (type == TokenType.STRING_INTERPOLATION_EXPRESSION) {
         token = token.next;
         type = token.type;
         //
@@ skipping 31 matching lines @@
       type = token.type;
       if (type == TokenType.STRING) {
         token = token.next;
         type = token.type;
       }
     }
     return token;
   }
 
   /**
-   * Parse a string literal, starting at the given token, without actually creating a string literal
-   * or changing the current token. Return the token following the string literal that was parsed,
-   * or `null` if the given token is not the first token in a valid string literal.
+   * Parse a string literal, starting at the [startToken], without actually
+   * creating a string literal or changing the current token. Return the token
+   * following the string literal that was parsed, or `null` if the given token
+   * is not the first token in a valid string literal.
    *
    * This method must be kept in sync with [parseStringLiteral].
    *
-   * <pre>
-   * stringLiteral ::=
-   *     MULTI_LINE_STRING+
-   *   | SINGLE_LINE_STRING+
-   * </pre>
-   *
-   * @param startToken the token at which parsing is to begin
-   * @return the token following the string literal that was parsed
+   *     stringLiteral ::=
+   *         MULTI_LINE_STRING+
+   *       | SINGLE_LINE_STRING+
    */
   Token _skipStringLiteral(Token startToken) {
     Token token = startToken;
     while (token != null && _tokenMatches(token, TokenType.STRING)) {
       token = token.next;
       TokenType type = token.type;
       if (type == TokenType.STRING_INTERPOLATION_EXPRESSION ||
           type == TokenType.STRING_INTERPOLATION_IDENTIFIER) {
         token = _skipStringInterpolation(token);
       }
     }
     if (identical(token, startToken)) {
       return null;
     }
     return token;
   }
 
   /**
-   * Parse a list of type arguments, starting at the given token, 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.
+   * 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].
    *
-   * <pre>
-   * typeArguments ::=
-   *     '<' typeList '>'
+   *     typeArguments ::=
+   *         '<' typeList '>'
    *
-   * typeList ::=
-   *     type (',' type)*
-   * </pre>
-   *
-   * @param startToken the token at which parsing is to begin
-   * @return the token following the type argument list that was parsed
+   *     typeList ::=
+   *         type (',' type)*
    */
   Token _skipTypeArgumentList(Token startToken) {
     Token token = startToken;
     if (!_tokenMatches(token, TokenType.LT)) {
       return null;
     }
     token = _skipTypeName(token.next);
     if (token == null) {
       return null;
     }
     while (_tokenMatches(token, TokenType.COMMA)) {
       token = _skipTypeName(token.next);
       if (token == null) {
         return null;
       }
     }
     if (token.type == TokenType.GT) {
       return token.next;
     } else if (token.type == TokenType.GT_GT) {
       Token second = new Token(TokenType.GT, token.offset + 1);
       second.setNextWithoutSettingPrevious(token.next);
       return second;
     }
     return null;
   }
 
   /**
-   * Parse a type name, starting at the given token, without actually creating a type name or
-   * changing the current token. Return the token following the type name that was parsed, or
-   * `null` if the given token is not the first token in a valid type name.
+   * Parse a type name, starting at the [startToken], without actually creating
+   * a type name or changing the current token. Return the token following the
+   * type name that was parsed, or `null` if the given token is not the first
+   * token in a valid type name.
    *
    * This method must be kept in sync with [parseTypeName].
    *
-   * <pre>
-   * type ::=
-   *     qualified typeArguments?
-   * </pre>
-   *
-   * @param startToken the token at which parsing is to begin
-   * @return the token following the type name that was parsed
+   *     type ::=
+   *         qualified typeArguments?
    */
   Token _skipTypeName(Token startToken) {
     Token token = _skipPrefixedIdentifier(startToken);
     if (token == null) {
       return null;
     }
     if (_tokenMatches(token, TokenType.LT)) {
       token = _skipTypeArgumentList(token);
     }
     return token;
   }
 
   /**
-   * Parse a list of type parameters, starting at the given token, without actually creating a type
-   * parameter list or changing the current token. Return the token following the type parameter
-   * list that was parsed, or `null` if the given token is not the first token in a valid type
-   * parameter list.
+   * Parse a list of type parameters, starting at the [startToken], without
+   * actually creating a type parameter list or changing the current token.
+   * Return the token following the type parameter list that was parsed, or
+   * `null` if the given token is not the first token in a valid type parameter
+   * list.
    *
    * This method must be kept in sync with [parseTypeParameterList].
    *
-   * <pre>
-   * typeParameterList ::=
-   *     '<' typeParameter (',' typeParameter)* '>'
-   * </pre>
-   *
-   * @param startToken the token at which parsing is to begin
-   * @return the token following the type parameter list that was parsed
+   *     typeParameterList ::=
+   *         '<' typeParameter (',' typeParameter)* '>'
    */
   Token _skipTypeParameterList(Token startToken) {
     if (!_tokenMatches(startToken, TokenType.LT)) {
       return null;
     }
     //
     // We can't skip a type parameter because it can be preceeded by metadata,
     // so we just assume that everything before the matching end token is valid.
     //
     int depth = 1;
@@ skipping 23 matching lines @@
           return fakeEquals;
         }
         depth -= 2;
       }
       next = next.next;
     }
     return next;
   }
 
   /**
-   * Return `true` if the given token has the given type.
-   *
-   * @param token the token being tested
-   * @param type the type of token that is being tested for
-   * @return `true` if the given token has the given type
+   * Return `true` if the given [token] has the given [type].
    */
   bool _tokenMatches(Token token, TokenType type) => token.type == type;
 
   /**
-   * Return `true` if the given token is a valid identifier. Valid identifiers include
-   * built-in identifiers (pseudo-keywords).
-   *
-   * @return `true` if the given token is a valid identifier
+   * Return `true` if the given [token] is a valid identifier. Valid identifiers
+   * include built-in identifiers (pseudo-keywords).
    */
   bool _tokenMatchesIdentifier(Token token) =>
       _tokenMatches(token, TokenType.IDENTIFIER) ||
           (_tokenMatches(token, TokenType.KEYWORD) &&
               (token as KeywordToken).keyword.isPseudoKeyword);
 
   /**
-   * Return `true` if the given token matches the given keyword.
-   *
-   * @param token the token being tested
-   * @param keyword the keyword that is being tested for
-   * @return `true` if the given token matches the given keyword
+   * Return `true` if the given [token] matches the given [keyword].
    */
   bool _tokenMatchesKeyword(Token token, Keyword keyword) =>
       token.type == TokenType.KEYWORD &&
           (token as KeywordToken).keyword == keyword;
 
   /**
-   * Return `true` if the given token matches the given identifier.
-   *
-   * @param token the token being tested
-   * @param identifier the identifier that can optionally appear in the current location
-   * @return `true` if the current token matches the given identifier
+   * Return `true` if the given [token] matches the given [identifier].
    */
   bool _tokenMatchesString(Token token, String identifier) =>
       token.type == TokenType.IDENTIFIER && token.lexeme == identifier;
 
   /**
    * Translate the characters at the given [index] in the given [lexeme],
    * appending the translated character to the given [buffer]. The index is
    * assumed to be valid.
    */
   int _translateCharacter(StringBuffer buffer, String lexeme, int index) {
@@ skipping 137 matching lines @@
    */
   void _unlockErrorListener() {
     if (_errorListenerLock == 0) {
       throw new IllegalStateException(
           "Attempt to unlock not locked error listener.");
     }
     _errorListenerLock--;
   }
 
   /**
-   * Validate that the given parameter list does not contain any field initializers.
-   *
-   * @param parameterList the parameter list to be validated
+   * Validate that the given [parameterList] does not contain any field
+   * initializers.
    */
   void _validateFormalParameterList(FormalParameterList parameterList) {
     for (FormalParameter parameter in parameterList.parameters) {
       if (parameter is FieldFormalParameter) {
         _reportErrorForNode(
             ParserErrorCode.FIELD_INITIALIZER_OUTSIDE_CONSTRUCTOR,
             parameter.identifier);
       }
     }
   }
 
   /**
-   * Validate that the given set of modifiers is appropriate for a class and return the 'abstract'
-   * keyword if there is one.
-   *
-   * @param modifiers the modifiers being validated
+   * Validate that the given set of [modifiers] is appropriate for a class and
+   * return the 'abstract' keyword if there is one.
    */
   Token _validateModifiersForClass(Modifiers modifiers) {
     _validateModifiersForTopLevelDeclaration(modifiers);
     if (modifiers.constKeyword != null) {
       _reportErrorForToken(ParserErrorCode.CONST_CLASS, modifiers.constKeyword);
     }
     if (modifiers.externalKeyword != null) {
       _reportErrorForToken(
           ParserErrorCode.EXTERNAL_CLASS, modifiers.externalKeyword);
     }
     if (modifiers.finalKeyword != null) {
       _reportErrorForToken(ParserErrorCode.FINAL_CLASS, modifiers.finalKeyword);
     }
     if (modifiers.varKeyword != null) {
       _reportErrorForToken(ParserErrorCode.VAR_CLASS, modifiers.varKeyword);
     }
     return modifiers.abstractKeyword;
   }
 
   /**
-   * Validate that the given set of modifiers is appropriate for a constructor and return the
-   * 'const' keyword if there is one.
-   *
-   * @param modifiers the modifiers being validated
-   * @return the 'const' or 'final' keyword associated with the constructor
+   * Validate that the given set of [modifiers] is appropriate for a constructor
+   * and return the 'const' keyword if there is one.
    */
   Token _validateModifiersForConstructor(Modifiers modifiers) {
     if (modifiers.abstractKeyword != null) {
       _reportErrorForToken(
           ParserErrorCode.ABSTRACT_CLASS_MEMBER, modifiers.abstractKeyword);
     }
     if (modifiers.finalKeyword != null) {
       _reportErrorForToken(
           ParserErrorCode.FINAL_CONSTRUCTOR, modifiers.finalKeyword);
     }
@@ skipping 17 matching lines @@
     if (externalKeyword != null &&
         factoryKeyword != null &&
         factoryKeyword.offset < externalKeyword.offset) {
       _reportErrorForToken(
           ParserErrorCode.EXTERNAL_AFTER_FACTORY, externalKeyword);
     }
     return constKeyword;
   }
 
   /**
-   * Validate that the given set of modifiers is appropriate for a class and return the 'abstract'
-   * keyword if there is one.
-   *
-   * @param modifiers the modifiers being validated
+   * Validate that the given set of [modifiers] is appropriate for a class and
+   * return the 'abstract' keyword if there is one.
    */
   void _validateModifiersForEnum(Modifiers modifiers) {
     _validateModifiersForTopLevelDeclaration(modifiers);
     if (modifiers.abstractKeyword != null) {
       _reportErrorForToken(
           ParserErrorCode.ABSTRACT_ENUM, modifiers.abstractKeyword);
     }
     if (modifiers.constKeyword != null) {
       _reportErrorForToken(ParserErrorCode.CONST_ENUM, modifiers.constKeyword);
     }
     if (modifiers.externalKeyword != null) {
       _reportErrorForToken(
           ParserErrorCode.EXTERNAL_ENUM, modifiers.externalKeyword);
     }
     if (modifiers.finalKeyword != null) {
       _reportErrorForToken(ParserErrorCode.FINAL_ENUM, modifiers.finalKeyword);
     }
     if (modifiers.varKeyword != null) {
       _reportErrorForToken(ParserErrorCode.VAR_ENUM, modifiers.varKeyword);
     }
   }
 
   /**
-   * Validate that the given set of modifiers is appropriate for a field and return the 'final',
-   * 'const' or 'var' keyword if there is one.
-   *
-   * @param modifiers the modifiers being validated
-   * @return the 'final', 'const' or 'var' keyword associated with the field
+   * Validate that the given set of [modifiers] is appropriate for a field and
+   * return the 'final', 'const' or 'var' keyword if there is one.
    */
   Token _validateModifiersForField(Modifiers modifiers) {
     if (modifiers.abstractKeyword != null) {
       _reportErrorForCurrentToken(ParserErrorCode.ABSTRACT_CLASS_MEMBER);
     }
     if (modifiers.externalKeyword != null) {
       _reportErrorForToken(
           ParserErrorCode.EXTERNAL_FIELD, modifiers.externalKeyword);
     }
     if (modifiers.factoryKeyword != null) {
@@ skipping 23 matching lines @@
       }
     } else if (varKeyword != null &&
         staticKeyword != null &&
         varKeyword.offset < staticKeyword.offset) {
       _reportErrorForToken(ParserErrorCode.STATIC_AFTER_VAR, staticKeyword);
     }
     return Token.lexicallyFirst([constKeyword, finalKeyword, varKeyword]);
   }
 
   /**
-   * Validate that the given set of modifiers is appropriate for a local function.
-   *
-   * @param modifiers the modifiers being validated
+   * Validate that the given set of [modifiers] is appropriate for a local
+   * function.
    */
   void _validateModifiersForFunctionDeclarationStatement(Modifiers modifiers) {
     if (modifiers.abstractKeyword != null ||
         modifiers.constKeyword != null ||
         modifiers.externalKeyword != null ||
         modifiers.factoryKeyword != null ||
         modifiers.finalKeyword != null ||
         modifiers.staticKeyword != null ||
         modifiers.varKeyword != null) {
       _reportErrorForCurrentToken(
           ParserErrorCode.LOCAL_FUNCTION_DECLARATION_MODIFIER);
     }
   }
 
   /**
-   * Validate that the given set of modifiers is appropriate for a getter, setter, or method.
-   *
-   * @param modifiers the modifiers being validated
+   * Validate that the given set of [modifiers] is appropriate for a getter,
+   * setter, or method.
    */
   void _validateModifiersForGetterOrSetterOrMethod(Modifiers modifiers) {
     if (modifiers.abstractKeyword != null) {
       _reportErrorForCurrentToken(ParserErrorCode.ABSTRACT_CLASS_MEMBER);
     }
     if (modifiers.constKeyword != null) {
       _reportErrorForToken(
           ParserErrorCode.CONST_METHOD, modifiers.constKeyword);
     }
     if (modifiers.factoryKeyword != null) {
@@ skipping 12 matching lines @@
     Token staticKeyword = modifiers.staticKeyword;
     if (externalKeyword != null &&
         staticKeyword != null &&
         staticKeyword.offset < externalKeyword.offset) {
       _reportErrorForToken(
           ParserErrorCode.EXTERNAL_AFTER_STATIC, externalKeyword);
     }
   }
 
   /**
-   * Validate that the given set of modifiers is appropriate for a getter, setter, or method.
-   *
-   * @param modifiers the modifiers being validated
+   * Validate that the given set of [modifiers] is appropriate for a getter,
+   * setter, or method.
    */
   void _validateModifiersForOperator(Modifiers modifiers) {
     if (modifiers.abstractKeyword != null) {
       _reportErrorForCurrentToken(ParserErrorCode.ABSTRACT_CLASS_MEMBER);
     }
     if (modifiers.constKeyword != null) {
       _reportErrorForToken(
           ParserErrorCode.CONST_METHOD, modifiers.constKeyword);
     }
     if (modifiers.factoryKeyword != null) {
       _reportErrorForToken(
           ParserErrorCode.NON_CONSTRUCTOR_FACTORY, modifiers.factoryKeyword);
     }
     if (modifiers.finalKeyword != null) {
       _reportErrorForToken(
           ParserErrorCode.FINAL_METHOD, modifiers.finalKeyword);
     }
     if (modifiers.staticKeyword != null) {
       _reportErrorForToken(
           ParserErrorCode.STATIC_OPERATOR, modifiers.staticKeyword);
     }
     if (modifiers.varKeyword != null) {
       _reportErrorForToken(
           ParserErrorCode.VAR_RETURN_TYPE, modifiers.varKeyword);
     }
   }
 
   /**
-   * Validate that the given set of modifiers is appropriate for a top-level declaration.
-   *
-   * @param modifiers the modifiers being validated
+   * Validate that the given set of [modifiers] is appropriate for a top-level
+   * declaration.
    */
   void _validateModifiersForTopLevelDeclaration(Modifiers modifiers) {
     if (modifiers.factoryKeyword != null) {
       _reportErrorForToken(ParserErrorCode.FACTORY_TOP_LEVEL_DECLARATION,
           modifiers.factoryKeyword);
     }
     if (modifiers.staticKeyword != null) {
       _reportErrorForToken(ParserErrorCode.STATIC_TOP_LEVEL_DECLARATION,
           modifiers.staticKeyword);
     }
   }
 
   /**
-   * Validate that the given set of modifiers is appropriate for a top-level function.
-   *
-   * @param modifiers the modifiers being validated
+   * Validate that the given set of [modifiers] is appropriate for a top-level
+   * function.
    */
   void _validateModifiersForTopLevelFunction(Modifiers modifiers) {
     _validateModifiersForTopLevelDeclaration(modifiers);
     if (modifiers.abstractKeyword != null) {
       _reportErrorForCurrentToken(ParserErrorCode.ABSTRACT_TOP_LEVEL_FUNCTION);
     }
     if (modifiers.constKeyword != null) {
       _reportErrorForToken(ParserErrorCode.CONST_CLASS, modifiers.constKeyword);
     }
     if (modifiers.finalKeyword != null) {
       _reportErrorForToken(ParserErrorCode.FINAL_CLASS, modifiers.finalKeyword);
     }
     if (modifiers.varKeyword != null) {
       _reportErrorForToken(
           ParserErrorCode.VAR_RETURN_TYPE, modifiers.varKeyword);
     }
   }
 
   /**
-   * Validate that the given set of modifiers is appropriate for a field and return the 'final',
-   * 'const' or 'var' keyword if there is one.
-   *
-   * @param modifiers the modifiers being validated
-   * @return the 'final', 'const' or 'var' keyword associated with the field
+   * Validate that the given set of [modifiers] is appropriate for a field and
+   * return the 'final', 'const' or 'var' keyword if there is one.
    */
   Token _validateModifiersForTopLevelVariable(Modifiers modifiers) {
     _validateModifiersForTopLevelDeclaration(modifiers);
     if (modifiers.abstractKeyword != null) {
       _reportErrorForCurrentToken(ParserErrorCode.ABSTRACT_TOP_LEVEL_VARIABLE);
     }
     if (modifiers.externalKeyword != null) {
       _reportErrorForToken(
           ParserErrorCode.EXTERNAL_FIELD, modifiers.externalKeyword);
     }
     Token constKeyword = modifiers.constKeyword;
     Token finalKeyword = modifiers.finalKeyword;
     Token varKeyword = modifiers.varKeyword;
     if (constKeyword != null) {
       if (finalKeyword != null) {
         _reportErrorForToken(ParserErrorCode.CONST_AND_FINAL, finalKeyword);
       }
       if (varKeyword != null) {
         _reportErrorForToken(ParserErrorCode.CONST_AND_VAR, varKeyword);
       }
     } else if (finalKeyword != null) {
       if (varKeyword != null) {
         _reportErrorForToken(ParserErrorCode.FINAL_AND_VAR, varKeyword);
       }
     }
     return Token.lexicallyFirst([constKeyword, finalKeyword, varKeyword]);
   }
 
   /**
-   * Validate that the given set of modifiers is appropriate for a class and return the 'abstract'
-   * keyword if there is one.
-   *
-   * @param modifiers the modifiers being validated
+   * Validate that the given set of [modifiers] is appropriate for a class and
+   * return the 'abstract' keyword if there is one.
    */
   void _validateModifiersForTypedef(Modifiers modifiers) {
     _validateModifiersForTopLevelDeclaration(modifiers);
     if (modifiers.abstractKeyword != null) {
       _reportErrorForToken(
           ParserErrorCode.ABSTRACT_TYPEDEF, modifiers.abstractKeyword);
     }
     if (modifiers.constKeyword != null) {
       _reportErrorForToken(
           ParserErrorCode.CONST_TYPEDEF, modifiers.constKeyword);
     }
     if (modifiers.externalKeyword != null) {
       _reportErrorForToken(
           ParserErrorCode.EXTERNAL_TYPEDEF, modifiers.externalKeyword);
     }
     if (modifiers.finalKeyword != null) {
       _reportErrorForToken(
           ParserErrorCode.FINAL_TYPEDEF, modifiers.finalKeyword);
     }
     if (modifiers.varKeyword != null) {
       _reportErrorForToken(ParserErrorCode.VAR_TYPEDEF, modifiers.varKeyword);
     }
   }
 }
 /**
- * Instances of the class `SyntheticKeywordToken` implement a synthetic keyword token.
+ * A synthetic keyword token.
  */
 class Parser_SyntheticKeywordToken extends KeywordToken {
   /**
-   * Initialize a newly created token to represent the given keyword.
-   *
-   * @param keyword the keyword being represented by this token
-   * @param offset the offset from the beginning of the file to the first character in the token
+   * Initialize a newly created token to represent the given [keyword] at the
+   * given [offset].
    */
   Parser_SyntheticKeywordToken(Keyword keyword, int offset)
       : super(keyword, offset);
 
   @override
   int get length => 0;
 
   @override
   Token copy() => new Parser_SyntheticKeywordToken(keyword, offset);
 }
 
 /**
- * The enumeration `ParserErrorCode` defines the error codes used for errors
- * detected by the parser. The convention for this class is for the name of the
- * error code to indicate the problem that caused the error to be generated and
- * for the error message to explain what is wrong and, when appropriate, how the
- * problem can be corrected.
+ * The error codes used for errors detected by the parser. The convention for
+ * this class is for the name of the error code to indicate the problem that
+ * caused the error to be generated and for the error message to explain what
+ * is wrong and, when appropriate, how the problem can be corrected.
  */
 class ParserErrorCode extends ErrorCode {
   static const ParserErrorCode ABSTRACT_CLASS_MEMBER = const ParserErrorCode(
       'ABSTRACT_CLASS_MEMBER',
       "Members of classes cannot be declared to be 'abstract'");
 
   static const ParserErrorCode ABSTRACT_ENUM = const ParserErrorCode(
       'ABSTRACT_ENUM', "Enums cannot be declared to be 'abstract'");
 
   static const ParserErrorCode ABSTRACT_STATIC_METHOD = const ParserErrorCode(
@@ skipping 596 matching lines @@
       : super(name, message, correction);
 
   @override
   ErrorSeverity get errorSeverity => ErrorSeverity.ERROR;
 
   @override
   ErrorType get type => ErrorType.SYNTACTIC_ERROR;
 }
 
 /**
- * Instances of the class `ResolutionCopier` copies resolution information from one AST
- * structure to another as long as the structures of the corresponding children of a pair of nodes
- * are the same.
+ * An object that copies resolution information from one AST structure to
+ * another as long as the structures of the corresponding children of a pair of
+ * nodes are the same.
  */
 class ResolutionCopier implements AstVisitor<bool> {
   /**
-   * The AST node with which the node being visited is to be compared. This is only valid at the
-   * beginning of each visit method (until [isEqualNodes] is invoked).
+   * The AST node with which the node being visited is to be compared. This is
+   * only valid at the beginning of each visit method (until [isEqualNodes] is
+   * invoked).
    */
   AstNode _toNode;
 
   @override
   bool visitAdjacentStrings(AdjacentStrings node) {
     AdjacentStrings toNode = this._toNode as AdjacentStrings;
     return _isEqualNodeLists(node.strings, toNode.strings);
   }
 
   @override
@@ skipping 1186 matching lines @@
         _isEqualNodes(node.expression, toNode.expression),
         _isEqualTokens(node.semicolon, toNode.semicolon));
   }
 
   /**
    * Return `true` if all of the parameters are `true`.
    */
   bool _and(bool b1, bool b2, [bool b3 = true, bool b4 = true, bool b5 = true,
       bool b6 = true, bool b7 = true, bool b8 = true, bool b9 = true,
       bool b10 = true, bool b11 = true, bool b12 = true, bool b13 = true]) {
+    // TODO(brianwilkerson) Inline this method.
     return b1 &&
         b2 &&
         b3 &&
         b4 &&
         b5 &&
         b6 &&
         b7 &&
         b8 &&
         b9 &&
         b10 &&
         b11 &&
         b12 &&
         b13;
   }
 
   /**
-   * Return `true` if the given lists of AST nodes have the same size and corresponding
-   * elements are equal.
-   *
-   * @param first the first node being compared
-   * @param second the second node being compared
-   * @return `true` if the given AST nodes have the same size and corresponding elements are
-   *         equal
+   * Return `true` if the [first] and [second] lists of AST nodes have the same
+   * size and corresponding elements are equal.
    */
   bool _isEqualNodeLists(NodeList first, NodeList second) {
     if (first == null) {
       return second == null;
     } else if (second == null) {
       return false;
     }
     int size = first.length;
     if (second.length != size) {
       return false;
     }
     bool equal = true;
     for (int i = 0; i < size; i++) {
       if (!_isEqualNodes(first[i], second[i])) {
         equal = false;
       }
     }
     return equal;
   }
 
   /**
-   * Return `true` if the given AST nodes have the same structure. As a side-effect, if the
-   * nodes do have the same structure, any resolution data from the first node will be copied to the
-   * second node.
-   *
-   * @param fromNode the node from which resolution information will be copied
-   * @param toNode the node to which resolution information will be copied
-   * @return `true` if the given AST nodes have the same structure
+   * Return `true` if the [fromNode] and [toNode] have the same structure. As a
+   * side-effect, if the nodes do have the same structure, any resolution data
+   * from the first node will be copied to the second node.
    */
   bool _isEqualNodes(AstNode fromNode, AstNode toNode) {
     if (fromNode == null) {
       return toNode == null;
     } else if (toNode == null) {
       return false;
     } else if (fromNode.runtimeType == toNode.runtimeType) {
       this._toNode = toNode;
       return fromNode.accept(this);
     }
@@ skipping 10 matching lines @@
       Expression target = toNode.target;
       if (fromNode.runtimeType == target.runtimeType) {
         this._toNode = target;
         return fromNode.accept(this);
       }
     }
     return false;
   }
 
   /**
-   * Return `true` if the given arrays of tokens have the same length and corresponding
-   * elements are equal.
-   *
-   * @param first the first node being compared
-   * @param second the second node being compared
-   * @return `true` if the given arrays of tokens have the same length and corresponding
-   *         elements are equal
+   * Return `true` if the [first] and [second] arrays of tokens have the same
+   * length and corresponding elements are equal.
    */
   bool _isEqualTokenLists(List<Token> first, List<Token> second) {
     int length = first.length;
     if (second.length != length) {
       return false;
     }
     for (int i = 0; i < length; i++) {
       if (!_isEqualTokens(first[i], second[i])) {
         return false;
       }
     }
     return true;
   }
 
   /**
-   * Return `true` if the given tokens have the same structure.
-   *
-   * @param first the first node being compared
-   * @param second the second node being compared
-   * @return `true` if the given tokens have the same structure
+   * Return `true` if the [first] and [second] tokens have the same structure.
    */
   bool _isEqualTokens(Token first, Token second) {
     if (first == null) {
       return second == null;
     } else if (second == null) {
       return false;
     }
     return first.lexeme == second.lexeme;
   }
 
   /**
-   * Copy resolution data from one node to another.
-   *
-   * @param fromNode the node from which resolution information will be copied
-   * @param toNode the node to which resolution information will be copied
+   * Copy resolution data from the [fromNode] to the [toNode].
    */
   static void copyResolutionData(AstNode fromNode, AstNode toNode) {
     ResolutionCopier copier = new ResolutionCopier();
     copier._isEqualNodes(fromNode, toNode);
   }
 }