Issue 8742. Preserve leading line comments during java2dart translation.

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:collection';
@@ skipping 206 matching lines @@
 
   ASTNode visitAssertStatement(AssertStatement node) {
     if (identical(_oldNode, node.condition)) {
       return _parser.parseExpression3();
     }
     return notAChild(node);
   }
 
   ASTNode visitAssignmentExpression(AssignmentExpression node) {
     if (identical(_oldNode, node.leftHandSide)) {
+      // TODO(brianwilkerson) If the assignment is part of a cascade section, then we don't have a
+      // single parse method that will work. Otherwise, we can parse a conditional expression, but
+      // need to ensure that the resulting expression is assignable.
+      // return parser.parseConditionalExpression();
       throw new InsufficientContextException();
     } else if (identical(_oldNode, node.rightHandSide)) {
       if (isCascadeAllowed(node)) {
         return _parser.parseExpression3();
       }
       return _parser.parseExpressionWithoutCascade();
     }
     return notAChild(node);
   }
 
@@ skipping 265 matching lines @@
       throw new InsufficientContextException();
     } else if (identical(_oldNode, node.identifier)) {
       return _parser.parseSimpleIdentifier();
     } else if (identical(_oldNode, node.body)) {
       return _parser.parseStatement2();
     }
     return notAChild(node);
   }
 
   ASTNode visitFormalParameterList(FormalParameterList node) {
+    // We don't know which kind of parameter to parse.
     throw new InsufficientContextException();
   }
 
   ASTNode visitForStatement(ForStatement node) {
     if (identical(_oldNode, node.variables)) {
       throw new InsufficientContextException();
     } else if (identical(_oldNode, node.initialization)) {
       throw new InsufficientContextException();
     } else if (identical(_oldNode, node.condition)) {
       return _parser.parseExpression3();
@@ skipping 227 matching lines @@
     } else if (node.metadata.contains(_oldNode)) {
       return _parser.parseAnnotation();
     } else if (identical(_oldNode, node.returnType)) {
       throw new InsufficientContextException();
     } else if (identical(_oldNode, node.name)) {
       if (node.operatorKeyword != null) {
         throw new InsufficientContextException();
       }
       return _parser.parseSimpleIdentifier();
     } else if (identical(_oldNode, node.body)) {
+      //return parser.parseFunctionBody();
       throw new InsufficientContextException();
     }
     return notAChild(node);
   }
 
   ASTNode visitMethodInvocation(MethodInvocation node) {
     if (identical(_oldNode, node.target)) {
       throw new IncrementalParseException();
     } else if (identical(_oldNode, node.methodName)) {
       return _parser.parseSimpleIdentifier();
@@ skipping 300 matching lines @@
   }
 
   /**
    * 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
    */
   bool isCascadeAllowed(AssignmentExpression node) {
+    // 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
    */
   bool isCascadeAllowed2(ThrowExpression node) {
+    // 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
    */
   ASTNode notAChild(ASTNode visitedNode) {
@@ skipping 81 matching lines @@
    * @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)) {
+      // If there are no new tokens, then we need to include at least one copied node in the range.
       firstToken = leftToken;
     }
+    //
+    // Find the smallest AST node that encompasses the range of re-scanned tokens.
+    //
     if (originalEnd < originalStart) {
       oldNode = new NodeLocator.con1(originalStart).searchWithin(originalStructure);
     } else {
       oldNode = new NodeLocator.con2(originalStart, originalEnd).searchWithin(originalStructure);
     }
+    //
+    // Find the token at which parsing is to begin.
+    //
     int originalOffset = oldNode.offset;
     Token parseToken = findTokenAt(firstToken, originalOffset);
     if (parseToken == null) {
       return null;
     }
+    //
+    // Parse the appropriate AST structure starting at the appropriate place.
+    //
     Parser parser = new Parser(_source, _errorListener);
     parser.currentToken = parseToken;
     while (newNode == null) {
       ASTNode parent = oldNode.parent;
       if (parent == null) {
         parseToken = findFirstToken(parseToken);
         parser.currentToken = parseToken;
         return parser.parseCompilationUnit2();
       }
       bool advanceToParent = false;
       try {
         IncrementalParseDispatcher dispatcher = new IncrementalParseDispatcher(parser, oldNode);
         newNode = parent.accept(dispatcher);
+        //
+        // Validate that the new node can replace the old node.
+        //
         Token mappedToken = _tokenMap.get(oldNode.endToken.next);
         if (mappedToken == null || mappedToken.offset != newNode.endToken.next.offset || newNode.offset != oldNode.offset) {
           advanceToParent = true;
         }
       } on InsufficientContextException catch (exception) {
         advanceToParent = true;
       } on JavaException catch (exception) {
         return null;
       }
       if (advanceToParent) {
         newNode = null;
         oldNode = parent;
         originalOffset = oldNode.offset;
         parseToken = findTokenAt(parseToken, originalOffset);
         parser.currentToken = parseToken;
       }
     }
     _updatedNode = newNode;
+    //
+    // Replace the old node with the new node in a copy of the original AST structure.
+    //
     if (identical(oldNode, originalStructure)) {
+      // We ended up re-parsing the whole structure, so there's no need for a copy.
       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.
@@ skipping 223 matching lines @@
    *     namedArgument
    *   | expression
    *
    * namedArgument ::=
    *     label expression
    * </pre>
    *
    * @return the argument that was parsed
    */
   Expression parseArgument() {
+    //
+    // Both namedArgument and expression can start with an identifier, but only namedArgument can
+    // have an identifier followed by a colon.
+    //
     if (matchesIdentifier() && matches4(peek(), TokenType.COLON)) {
       return new NamedExpression(parseLabel(), parseExpression3());
     } else {
       return parseExpression3();
     }
   }
 
   /**
    * Parse a list of arguments.
    *
    * <pre>
    * arguments ::=
    *     '(' argumentList? ')'
    *
    * argumentList ::=
    *     namedArgument (',' namedArgument)*
    *   | expressionList (',' namedArgument)*
    * </pre>
    *
    * @return the argument list that was parsed
    */
   ArgumentList parseArgumentList() {
     Token leftParenthesis = expect2(TokenType.OPEN_PAREN);
     List<Expression> arguments = new List<Expression>();
     if (matches5(TokenType.CLOSE_PAREN)) {
       return new ArgumentList(leftParenthesis, arguments, andAdvance);
     }
+    //
+    // 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.
+    //
     Expression argument = parseArgument();
     arguments.add(argument);
     bool foundNamedArgument = argument is NamedExpression;
     bool generatedError = false;
     while (optional(TokenType.COMMA)) {
       argument = parseArgument();
       arguments.add(argument);
       if (foundNamedArgument) {
         if (!generatedError && argument is! NamedExpression) {
+          // Report the error, once, but allow the arguments to be in any order in the AST.
           reportError11(ParserErrorCode.POSITIONAL_AFTER_NAMED_ARGUMENT, []);
           generatedError = true;
         }
       } else if (argument is NamedExpression) {
         foundNamedArgument = true;
       }
     }
+    // TODO(brianwilkerson) Recovery: Look at the left parenthesis to see 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 = expect2(TokenType.CLOSE_PAREN);
     return new ArgumentList(leftParenthesis, arguments, rightParenthesis);
   }
 
   /**
    * Parse a bitwise or expression.
    *
    * <pre>
    * bitwiseOrExpression ::=
    *     bitwiseXorExpression ('|' bitwiseXorExpression)*
@@ skipping 29 matching lines @@
   Block parseBlock() {
     Token leftBracket = expect2(TokenType.OPEN_CURLY_BRACKET);
     List<Statement> statements = new List<Statement>();
     Token statementStart = _currentToken;
     while (!matches5(TokenType.EOF) && !matches5(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.
         reportError12(ParserErrorCode.UNEXPECTED_TOKEN, _currentToken, [_currentToken.lexeme]);
         advance();
       }
       statementStart = _currentToken;
     }
     Token rightBracket = expect2(TokenType.CLOSE_CURLY_BRACKET);
     return new Block(leftBracket, statements, rightBracket);
   }
 
   /**
@@ skipping 23 matching lines @@
       } else if (matches(Keyword.OPERATOR) && isOperator(peek())) {
         validateModifiersForOperator(modifiers);
         return parseOperator(commentAndMetadata, modifiers.externalKeyword, returnType);
       } else if (matchesIdentifier() && matchesAny(peek(), [
           TokenType.OPEN_PAREN,
           TokenType.OPEN_CURLY_BRACKET,
           TokenType.FUNCTION])) {
         validateModifiersForGetterOrSetterOrMethod(modifiers);
         return parseMethodDeclaration(commentAndMetadata, modifiers.externalKeyword, modifiers.staticKeyword, returnType);
       } else {
+        //
+        // We have found an error of some kind. Try to recover.
+        //
         if (matchesIdentifier()) {
           if (matchesAny(peek(), [TokenType.EQ, TokenType.COMMA, TokenType.SEMICOLON])) {
+            //
+            // We appear to have a variable declaration with a type of "void".
+            //
             reportError10(ParserErrorCode.VOID_VARIABLE, returnType, []);
             return parseInitializedIdentifierList(commentAndMetadata, modifiers.staticKeyword, validateModifiersForField(modifiers), returnType);
           }
         }
         if (isOperator(_currentToken)) {
+          //
+          // We appear to have found an operator declaration without the 'operator' keyword.
+          //
           validateModifiersForOperator(modifiers);
           return parseOperator(commentAndMetadata, modifiers.externalKeyword, returnType);
         }
         reportError12(ParserErrorCode.EXPECTED_EXECUTABLE, _currentToken, []);
         return null;
       }
     } else if (matches(Keyword.GET) && matchesIdentifier2(peek())) {
       validateModifiersForGetterOrSetterOrMethod(modifiers);
       return parseGetter(commentAndMetadata, modifiers.externalKeyword, modifiers.staticKeyword, null);
     } else if (matches(Keyword.SET) && matchesIdentifier2(peek())) {
       validateModifiersForGetterOrSetterOrMethod(modifiers);
       return parseSetter(commentAndMetadata, modifiers.externalKeyword, modifiers.staticKeyword, null);
     } else if (matches(Keyword.OPERATOR) && isOperator(peek())) {
       validateModifiersForOperator(modifiers);
       return parseOperator(commentAndMetadata, modifiers.externalKeyword, null);
     } else if (!matchesIdentifier()) {
       if (isOperator(_currentToken)) {
+        //
+        // We appear to have found an operator declaration without the 'operator' keyword.
+        //
         validateModifiersForOperator(modifiers);
         return parseOperator(commentAndMetadata, modifiers.externalKeyword, null);
       }
       reportError12(ParserErrorCode.EXPECTED_CLASS_MEMBER, _currentToken, []);
       return null;
     } else if (matches4(peek(), TokenType.PERIOD) && matchesIdentifier2(peek2(2)) && matches4(peek2(3), TokenType.OPEN_PAREN)) {
       return parseConstructor(commentAndMetadata, modifiers.externalKeyword, validateModifiersForConstructor(modifiers), modifiers.factoryKeyword, parseSimpleIdentifier(), andAdvance, parseSimpleIdentifier(), parseFormalParameterList());
     } else if (matches4(peek(), TokenType.OPEN_PAREN)) {
       SimpleIdentifier methodName = parseSimpleIdentifier();
       FormalParameterList parameters = parseFormalParameterList();
@@ skipping 14 matching lines @@
       validateModifiersForGetterOrSetterOrMethod(modifiers);
       return parseGetter(commentAndMetadata, modifiers.externalKeyword, modifiers.staticKeyword, type);
     } else if (matches(Keyword.SET) && matchesIdentifier2(peek())) {
       validateModifiersForGetterOrSetterOrMethod(modifiers);
       return parseSetter(commentAndMetadata, modifiers.externalKeyword, modifiers.staticKeyword, type);
     } else if (matches(Keyword.OPERATOR) && isOperator(peek())) {
       validateModifiersForOperator(modifiers);
       return parseOperator(commentAndMetadata, modifiers.externalKeyword, type);
     } else if (!matchesIdentifier()) {
       if (matches5(TokenType.CLOSE_CURLY_BRACKET)) {
+        //
+        // We appear to have found an incomplete declaration at the end of the class. At this point
+        // it consists of a type name, so we'll treat it as a field declaration with a missing
+        // field name and semicolon.
+        //
         return parseInitializedIdentifierList(commentAndMetadata, modifiers.staticKeyword, validateModifiersForField(modifiers), type);
       }
       if (isOperator(_currentToken)) {
+        //
+        // We appear to have found an operator declaration without the 'operator' keyword.
+        //
         validateModifiersForOperator(modifiers);
         return parseOperator(commentAndMetadata, modifiers.externalKeyword, type);
       }
+      //
+      // We appear to have found an incomplete declaration before another declaration.
+      // At this point it consists of a type name, so we'll treat it as a field declaration
+      // with a missing field name and semicolon.
+      //
       reportError12(ParserErrorCode.EXPECTED_CLASS_MEMBER, _currentToken, []);
       try {
         lockErrorListener();
         return parseInitializedIdentifierList(commentAndMetadata, modifiers.staticKeyword, validateModifiersForField(modifiers), type);
       } finally {
         unlockErrorListener();
       }
     } else if (matches4(peek(), TokenType.OPEN_PAREN)) {
       SimpleIdentifier methodName = parseSimpleIdentifier();
       FormalParameterList parameters = parseFormalParameterList();
@@ skipping 29 matching lines @@
    * </pre>
    *
    * @return the compilation unit that was parsed
    */
   CompilationUnit parseCompilationUnit2() {
     Token firstToken = _currentToken;
     ScriptTag scriptTag = null;
     if (matches5(TokenType.SCRIPT_TAG)) {
       scriptTag = new ScriptTag(andAdvance);
     }
+    //
+    // Even though all directives must appear before declarations and must occur in a given order,
+    // we allow directives and declarations to occur in any order so that we can recover better.
+    //
     bool libraryDirectiveFound = false;
     bool partOfDirectiveFound = false;
     bool partDirectiveFound = false;
     bool directiveFoundAfterDeclaration = false;
     List<Directive> directives = new List<Directive>();
     List<CompilationUnitMember> declarations = new List<CompilationUnitMember>();
     Token memberStart = _currentToken;
     while (!matches5(TokenType.EOF)) {
       CommentAndMetadata commentAndMetadata = parseCommentAndMetadata();
       if ((matches(Keyword.IMPORT) || matches(Keyword.EXPORT) || matches(Keyword.LIBRARY) || matches(Keyword.PART)) && !matches4(peek(), TokenType.PERIOD) && !matches4(peek(), TokenType.LT) && !matches4(peek(), TokenType.OPEN_PAREN)) {
@@ skipping 111 matching lines @@
    * </pre>
    *
    * @return the expression that was parsed
    */
   Expression parseExpression3() {
     if (matches(Keyword.THROW)) {
       return parseThrowExpression();
     } else if (matches(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();
     TokenType tokenType = _currentToken.type;
     if (identical(tokenType, TokenType.PERIOD_PERIOD)) {
       List<Expression> cascadeSections = new List<Expression>();
       while (identical(tokenType, TokenType.PERIOD_PERIOD)) {
         Expression section = parseCascadeSection();
         if (section != null) {
           cascadeSections.add(section);
         }
         tokenType = _currentToken.type;
@@ skipping 18 matching lines @@
    * </pre>
    *
    * @return the expression that was parsed
    */
   Expression parseExpressionWithoutCascade() {
     if (matches(Keyword.THROW)) {
       return parseThrowExpressionWithoutCascade();
     } else if (matches(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 = andAdvance;
       ensureAssignable(expression);
       expression = new AssignmentExpression(expression, operator, parseExpressionWithoutCascade());
     }
     return expression;
   }
 
   /**
@@ skipping 35 matching lines @@
    *     '{' defaultNamedParameter (',' defaultNamedParameter)* '}'
    * </pre>
    *
    * @return the formal parameters that were parsed
    */
   FormalParameterList parseFormalParameterList() {
     Token leftParenthesis = expect2(TokenType.OPEN_PAREN);
     if (matches5(TokenType.CLOSE_PAREN)) {
       return new FormalParameterList(leftParenthesis, null, null, null, andAdvance);
     }
+    //
+    // Even though it is invalid to have default parameters outside of brackets, required parameters
+    // inside of brackets, or multiple groups of default and named parameters, we allow all of these
+    // cases so that we can recover better.
+    //
     List<FormalParameter> parameters = new List<FormalParameter>();
     List<FormalParameter> normalParameters = new List<FormalParameter>();
     List<FormalParameter> positionalParameters = new List<FormalParameter>();
     List<FormalParameter> namedParameters = new List<FormalParameter>();
     List<FormalParameter> currentParameters = normalParameters;
     Token leftSquareBracket = null;
     Token rightSquareBracket = null;
     Token leftCurlyBracket = null;
     Token rightCurlyBracket = null;
     ParameterKind kind = ParameterKind.REQUIRED;
     bool firstParameter = true;
     bool reportedMuliplePositionalGroups = false;
     bool reportedMulipleNamedGroups = false;
     bool reportedMixedGroups = false;
     bool wasOptionalParameter = false;
     Token initialToken = null;
     do {
       if (firstParameter) {
         firstParameter = false;
       } else if (!optional(TokenType.COMMA)) {
+        // TODO(brianwilkerson) The token is wrong, we need to recover from this case.
         if (getEndToken(leftParenthesis) != null) {
           reportError11(ParserErrorCode.EXPECTED_TOKEN, [TokenType.COMMA.lexeme]);
         } else {
           reportError12(ParserErrorCode.MISSING_CLOSING_PARENTHESIS, _currentToken.previous, []);
           break;
         }
       }
       initialToken = _currentToken;
+      //
+      // Handle the beginning of parameter groups.
+      //
       if (matches5(TokenType.OPEN_SQUARE_BRACKET)) {
         wasOptionalParameter = true;
         if (leftSquareBracket != null && !reportedMuliplePositionalGroups) {
           reportError11(ParserErrorCode.MULTIPLE_POSITIONAL_PARAMETER_GROUPS, []);
           reportedMuliplePositionalGroups = true;
         }
         if (leftCurlyBracket != null && !reportedMixedGroups) {
           reportError11(ParserErrorCode.MIXED_PARAMETER_GROUPS, []);
           reportedMixedGroups = true;
         }
         leftSquareBracket = andAdvance;
         currentParameters = positionalParameters;
         kind = ParameterKind.POSITIONAL;
       } else if (matches5(TokenType.OPEN_CURLY_BRACKET)) {
         wasOptionalParameter = true;
         if (leftCurlyBracket != null && !reportedMulipleNamedGroups) {
           reportError11(ParserErrorCode.MULTIPLE_NAMED_PARAMETER_GROUPS, []);
           reportedMulipleNamedGroups = true;
         }
         if (leftSquareBracket != null && !reportedMixedGroups) {
           reportError11(ParserErrorCode.MIXED_PARAMETER_GROUPS, []);
           reportedMixedGroups = true;
         }
         leftCurlyBracket = andAdvance;
         currentParameters = namedParameters;
         kind = ParameterKind.NAMED;
       }
+      //
+      // Parse and record the parameter.
+      //
       FormalParameter parameter = parseFormalParameter(kind);
       parameters.add(parameter);
       currentParameters.add(parameter);
       if (identical(kind, ParameterKind.REQUIRED) && wasOptionalParameter) {
         reportError10(ParserErrorCode.NORMAL_BEFORE_OPTIONAL_PARAMETERS, parameter, []);
       }
+      //
+      // Handle the end of parameter groups.
+      //
+      // TODO(brianwilkerson) Improve the detection and reporting of missing and mismatched delimiters.
       if (matches5(TokenType.CLOSE_SQUARE_BRACKET)) {
         rightSquareBracket = andAdvance;
         currentParameters = normalParameters;
         if (leftSquareBracket == null) {
           if (leftCurlyBracket != null) {
             reportError11(ParserErrorCode.WRONG_TERMINATOR_FOR_PARAMETER_GROUP, ["}"]);
             rightCurlyBracket = rightSquareBracket;
             rightSquareBracket = null;
           } else {
             reportError11(ParserErrorCode.UNEXPECTED_TERMINATOR_FOR_PARAMETER_GROUP, ["["]);
           }
         }
         kind = ParameterKind.REQUIRED;
       } else if (matches5(TokenType.CLOSE_CURLY_BRACKET)) {
         rightCurlyBracket = andAdvance;
         currentParameters = normalParameters;
         if (leftCurlyBracket == null) {
           if (leftSquareBracket != null) {
             reportError11(ParserErrorCode.WRONG_TERMINATOR_FOR_PARAMETER_GROUP, ["]"]);
             rightSquareBracket = rightCurlyBracket;
             rightCurlyBracket = null;
           } else {
             reportError11(ParserErrorCode.UNEXPECTED_TERMINATOR_FOR_PARAMETER_GROUP, ["{"]);
           }
         }
         kind = ParameterKind.REQUIRED;
       }
     } while (!matches5(TokenType.CLOSE_PAREN) && initialToken != _currentToken);
     Token rightParenthesis = expect2(TokenType.CLOSE_PAREN);
+    //
+    // Check that the groups were closed correctly.
+    //
     if (leftSquareBracket != null && rightSquareBracket == null) {
       reportError11(ParserErrorCode.MISSING_TERMINATOR_FOR_PARAMETER_GROUP, ["]"]);
     }
     if (leftCurlyBracket != null && rightCurlyBracket == null) {
       reportError11(ParserErrorCode.MISSING_TERMINATOR_FOR_PARAMETER_GROUP, ["}"]);
     }
+    //
+    // Build the parameter list.
+    //
     if (leftSquareBracket == null) {
       leftSquareBracket = leftCurlyBracket;
     }
     if (rightSquareBracket == null) {
       rightSquareBracket = rightCurlyBracket;
     }
     return new FormalParameterList(leftParenthesis, parameters, leftSquareBracket, rightSquareBracket, rightParenthesis);
   }
 
   /**
@@ skipping 478 matching lines @@
 
   /**
    * 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
    */
   bool couldBeStartOfCompilationUnitMember() {
     if ((matches(Keyword.IMPORT) || matches(Keyword.EXPORT) || matches(Keyword.LIBRARY) || matches(Keyword.PART)) && !matches4(peek(), TokenType.PERIOD) && !matches4(peek(), TokenType.LT)) {
+      // This looks like the start of a directive
       return true;
     } else if (matches(Keyword.CLASS)) {
+      // This looks like the start of a class definition
       return true;
     } else if (matches(Keyword.TYPEDEF) && !matches4(peek(), TokenType.PERIOD) && !matches4(peek(), TokenType.LT)) {
+      // This looks like the start of a typedef
       return true;
     } else if (matches(Keyword.VOID) || ((matches(Keyword.GET) || matches(Keyword.SET)) && matchesIdentifier2(peek())) || (matches(Keyword.OPERATOR) && isOperator(peek()))) {
+      // This looks like the start of a function
       return true;
     } else if (matchesIdentifier()) {
       if (matches4(peek(), TokenType.OPEN_PAREN)) {
+        // This looks like the start of a function
         return true;
       }
       Token token = skipReturnType(_currentToken);
       if (token == null) {
         return false;
       }
       if (matches(Keyword.GET) || matches(Keyword.SET) || (matches(Keyword.OPERATOR) && isOperator(peek())) || matchesIdentifier()) {
         return true;
       }
     }
     return false;
   }
 
   /**
    * Create a synthetic identifier.
    *
    * @return the synthetic identifier that was created
    */
   SimpleIdentifier createSyntheticIdentifier() {
     Token syntheticToken;
     if (identical(_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 = createSyntheticToken2(TokenType.IDENTIFIER);
     }
     return new SimpleIdentifier(syntheticToken);
   }
 
   /**
    * Create a synthetic string literal.
    *
@@ skipping 41 matching lines @@
    * 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
    */
   Token expect(Keyword keyword) {
     if (matches(keyword)) {
       return andAdvance;
     }
+    // Remove uses of this method in favor of matches?
+    // Pass in the error code to use to report the error?
     reportError11(ParserErrorCode.EXPECTED_TOKEN, [keyword.syntax]);
     return _currentToken;
   }
 
   /**
    * If the current token has the expected type, return it after advancing to the next token.
    * Otherwise report an error and return the current token without advancing.
    *
    * @param type the type of token that is expected
    * @return the token that matched the given type
    */
   Token expect2(TokenType type) {
     if (matches5(type)) {
       return andAdvance;
     }
+    // Remove uses of this method in favor of matches?
+    // Pass in the error code to use to report the error?
     if (identical(type, TokenType.SEMICOLON)) {
       reportError12(ParserErrorCode.EXPECTED_TOKEN, _currentToken.previous, [type.lexeme]);
     } else {
       reportError11(ParserErrorCode.EXPECTED_TOKEN, [type.lexeme]);
     }
     return _currentToken;
   }
 
   /**
    * Search the given list of ranges for a range that contains the given index. Return the range
@@ skipping 118 matching lines @@
    * Return `true` if the current token appears to be the beginning of a function declaration.
    *
    * @return `true` if the current token appears to be the beginning of a function declaration
    */
   bool isFunctionDeclaration() {
     if (matches(Keyword.VOID)) {
       return true;
     }
     Token afterReturnType = skipTypeName(_currentToken);
     if (afterReturnType == null) {
+      // There was no return type, but it is optional, so go back to where we started.
       afterReturnType = _currentToken;
     }
     Token afterIdentifier = skipSimpleIdentifier(afterReturnType);
     if (afterIdentifier == null) {
+      // It's possible that we parsed the function name as if it were a type name, so see whether
+      // it makes sense if we assume that there is no type.
       afterIdentifier = skipSimpleIdentifier(_currentToken);
     }
     if (afterIdentifier == null) {
       return false;
     }
     if (isFunctionExpression(afterIdentifier)) {
       return true;
     }
+    // It's possible that we have found a getter. While this isn't valid at this point we test for
+    // it in order to recover better.
     if (matches(Keyword.GET)) {
       Token afterName = skipSimpleIdentifier(_currentToken.next);
       if (afterName == null) {
         return false;
       }
       return matches4(afterName, TokenType.FUNCTION) || matches4(afterName, TokenType.OPEN_CURLY_BRACKET);
     }
     return false;
   }
 
@@ skipping 42 matching lines @@
    *
    * initializedIdentifier ::=
    *     identifier ('=' expression)?
    * </pre>
    *
    * @return `true` if the current token is the first token in an initialized variable
    *         declaration
    */
   bool isInitializedVariableDeclaration() {
     if (matches(Keyword.FINAL) || matches(Keyword.VAR)) {
+      // An expression cannot start with a keyword other than 'const', 'rethrow', or 'throw'.
       return true;
     }
     if (matches(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.
       return !matchesAny(peek(), [
           TokenType.LT,
           TokenType.OPEN_CURLY_BRACKET,
           TokenType.OPEN_SQUARE_BRACKET,
           TokenType.INDEX]);
     }
+    // We know that we have an identifier, and need to see whether it might be a type name.
     Token token = skipTypeName(_currentToken);
     if (token == null) {
+      // There was no type name, so this can't be a declaration.
       return false;
     }
     token = skipSimpleIdentifier(token);
     if (token == null) {
       return false;
     }
     TokenType type = token.type;
     return identical(type, TokenType.EQ) || identical(type, TokenType.COMMA) || identical(type, TokenType.SEMICOLON) || matches3(token, Keyword.IN);
   }
 
@@ skipping 29 matching lines @@
     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
    */
   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 (identical(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 matches4(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
    */
   bool isSwitchMember() {
     Token token = _currentToken;
@@ skipping 270 matching lines @@
    * </pre>
    *
    * @param primaryAllowed `true` if the expression is allowed to be a primary without any
    *          assignable selector
    * @return the assignable expression that was parsed
    */
   Expression parseAssignableExpression(bool primaryAllowed) {
     if (matches(Keyword.SUPER)) {
       return parseAssignableSelector(new SuperExpression(andAdvance), 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.
+    //
     Expression expression = parsePrimaryExpression();
     bool isOptional = primaryAllowed || expression is SimpleIdentifier;
     while (true) {
       while (matches5(TokenType.OPEN_PAREN)) {
         ArgumentList argumentList = parseArgumentList();
         if (expression is SimpleIdentifier) {
           expression = new MethodInvocation(null, null, expression as SimpleIdentifier, argumentList);
         } else if (expression is PrefixedIdentifier) {
           PrefixedIdentifier identifier = expression as PrefixedIdentifier;
           expression = new MethodInvocation(identifier.prefix, identifier.period, identifier.identifier, argumentList);
@@ skipping 37 matching lines @@
     if (matches5(TokenType.OPEN_SQUARE_BRACKET)) {
       Token leftBracket = andAdvance;
       Expression index = parseExpression3();
       Token rightBracket = expect2(TokenType.CLOSE_SQUARE_BRACKET);
       return new IndexExpression.forTarget(prefix, leftBracket, index, rightBracket);
     } else if (matches5(TokenType.PERIOD)) {
       Token period = andAdvance;
       return new PropertyAccess(prefix, period, parseSimpleIdentifier());
     } else {
       if (!optional) {
+        // Report the missing selector.
         reportError11(ParserErrorCode.MISSING_ASSIGNABLE_SELECTOR, []);
       }
       return prefix;
     }
   }
 
   /**
    * Parse a bitwise and expression.
    *
    * <pre>
@@ skipping 99 matching lines @@
       reportError12(ParserErrorCode.MISSING_IDENTIFIER, _currentToken, [_currentToken.lexeme]);
       functionName = createSyntheticIdentifier();
     }
     if (identical(_currentToken.type, TokenType.OPEN_PAREN)) {
       while (identical(_currentToken.type, TokenType.OPEN_PAREN)) {
         if (functionName != null) {
           expression = new MethodInvocation(expression, period, functionName, parseArgumentList());
           period = null;
           functionName = null;
         } else if (expression == null) {
+          // It should not be possible to get here.
           expression = new MethodInvocation(expression, period, createSyntheticIdentifier(), parseArgumentList());
         } else {
           expression = new FunctionExpressionInvocation(expression, parseArgumentList());
         }
       }
     } else if (functionName != null) {
       expression = new PropertyAccess(expression, period, functionName);
       period = null;
     }
     bool progress = true;
@@ skipping 47 matching lines @@
       } else if (matches4(next, TokenType.EQ)) {
         return parseClassTypeAlias(commentAndMetadata, abstractKeyword, keyword);
       }
     }
     SimpleIdentifier name = parseSimpleIdentifier();
     String className = name.name;
     TypeParameterList typeParameters = null;
     if (matches5(TokenType.LT)) {
       typeParameters = parseTypeParameterList();
     }
+    //
+    // Parse the clauses. The parser accepts clauses in any order, but will generate errors if they
+    // are not in the order required by the specification.
+    //
     ExtendsClause extendsClause = null;
     WithClause withClause = null;
     ImplementsClause implementsClause = null;
     bool foundClause = true;
     while (foundClause) {
       if (matches(Keyword.EXTENDS)) {
         if (extendsClause == null) {
           extendsClause = parseExtendsClause();
           if (withClause != null) {
             reportError12(ParserErrorCode.WITH_BEFORE_EXTENDS, withClause.withKeyword, []);
@@ skipping 21 matching lines @@
           reportError12(ParserErrorCode.MULTIPLE_IMPLEMENTS_CLAUSES, implementsClause.keyword, []);
           parseImplementsClause();
         }
       } else {
         foundClause = false;
       }
     }
     if (withClause != null && extendsClause == null) {
       reportError12(ParserErrorCode.WITH_WITHOUT_EXTENDS, withClause.withKeyword, []);
     }
+    //
+    // Look for and skip over the extra-lingual 'native' specification.
+    //
     NativeClause nativeClause = null;
     if (matches2(_NATIVE) && matches4(peek(), TokenType.STRING)) {
       nativeClause = parseNativeClause();
     }
+    //
+    // Parse the body of the class.
+    //
     Token leftBracket = null;
     List<ClassMember> members = null;
     Token rightBracket = null;
     if (matches5(TokenType.OPEN_CURLY_BRACKET)) {
       leftBracket = expect2(TokenType.OPEN_CURLY_BRACKET);
       members = parseClassMembers(className, getEndToken(leftBracket));
       rightBracket = expect2(TokenType.CLOSE_CURLY_BRACKET);
     } else {
       leftBracket = createSyntheticToken2(TokenType.OPEN_CURLY_BRACKET);
       rightBracket = createSyntheticToken2(TokenType.CLOSE_CURLY_BRACKET);
@@ skipping 149 matching lines @@
    * 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 parseCommentReference(String referenceSource, int sourceOffset) {
+    // TODO(brianwilkerson) The errors are not getting the right offset/length and are being duplicated.
     if (referenceSource.length == 0) {
       return null;
     }
     try {
       BooleanErrorListener listener = new BooleanErrorListener();
       Scanner scanner = new Scanner(null, new SubSequenceReader(new CharSequence(referenceSource), sourceOffset), listener);
       scanner.setSourceStart(1, 1);
       Token firstToken = scanner.tokenize();
       if (listener.errorReported) {
         return null;
@@ skipping 13 matching lines @@
           nextToken = thirdToken.next;
         } else {
           identifier = new SimpleIdentifier(firstToken);
           nextToken = firstToken.next;
         }
         if (nextToken.type != TokenType.EOF) {
           return null;
         }
         return new CommentReference(newKeyword, identifier);
       } else if (matches3(firstToken, Keyword.THIS) || matches3(firstToken, Keyword.NULL) || matches3(firstToken, Keyword.TRUE) || matches3(firstToken, Keyword.FALSE)) {
+        // TODO(brianwilkerson) If we want to support this we will need to extend the definition
+        // of CommentReference to take an expression rather than an identifier. For now we just
+        // ignore it to reduce the number of errors produced, but that's probably not a valid
+        // long term approach.
         return null;
       }
     } on JavaException catch (exception) {
     }
     return null;
   }
 
   /**
    * Parse all of the comment references occurring in the given array of documentation comments.
    *
@@ skipping 78 matching lines @@
       } else if (matches(Keyword.OPERATOR) && isOperator(peek())) {
         reportError12(ParserErrorCode.TOP_LEVEL_OPERATOR, _currentToken, []);
         return convertToFunctionDeclaration(parseOperator(commentAndMetadata, modifiers.externalKeyword, returnType));
       } else if (matchesIdentifier() && matchesAny(peek(), [
           TokenType.OPEN_PAREN,
           TokenType.OPEN_CURLY_BRACKET,
           TokenType.FUNCTION])) {
         validateModifiersForTopLevelFunction(modifiers);
         return parseFunctionDeclaration(commentAndMetadata, modifiers.externalKeyword, returnType);
       } else {
+        //
+        // We have found an error of some kind. Try to recover.
+        //
         if (matchesIdentifier()) {
           if (matchesAny(peek(), [TokenType.EQ, TokenType.COMMA, TokenType.SEMICOLON])) {
+            //
+            // We appear to have a variable declaration with a type of "void".
+            //
             reportError10(ParserErrorCode.VOID_VARIABLE, returnType, []);
             return new TopLevelVariableDeclaration(commentAndMetadata.comment, commentAndMetadata.metadata, parseVariableDeclarationList2(null, validateModifiersForTopLevelVariable(modifiers), null), expect2(TokenType.SEMICOLON));
           }
         }
         reportError12(ParserErrorCode.EXPECTED_EXECUTABLE, _currentToken, []);
         return null;
       }
     } else if ((matches(Keyword.GET) || matches(Keyword.SET)) && matchesIdentifier2(peek())) {
       validateModifiersForTopLevelFunction(modifiers);
       return parseFunctionDeclaration(commentAndMetadata, modifiers.externalKeyword, null);
@@ skipping 15 matching lines @@
     TypeName returnType = parseReturnType();
     if ((matches(Keyword.GET) || matches(Keyword.SET)) && matchesIdentifier2(peek())) {
       validateModifiersForTopLevelFunction(modifiers);
       return parseFunctionDeclaration(commentAndMetadata, modifiers.externalKeyword, returnType);
     } else if (matches(Keyword.OPERATOR) && isOperator(peek())) {
       reportError12(ParserErrorCode.TOP_LEVEL_OPERATOR, _currentToken, []);
       return convertToFunctionDeclaration(parseOperator(commentAndMetadata, modifiers.externalKeyword, returnType));
     } else if (matches5(TokenType.AT)) {
       return new TopLevelVariableDeclaration(commentAndMetadata.comment, commentAndMetadata.metadata, parseVariableDeclarationList2(null, validateModifiersForTopLevelVariable(modifiers), returnType), expect2(TokenType.SEMICOLON));
     } else if (!matchesIdentifier()) {
+      // TODO(brianwilkerson) Generalize this error. We could also be parsing a top-level variable at this point.
       reportError12(ParserErrorCode.EXPECTED_EXECUTABLE, _currentToken, []);
       Token semicolon;
       if (matches5(TokenType.SEMICOLON)) {
         semicolon = andAdvance;
       } else {
         semicolon = createSyntheticToken2(TokenType.SEMICOLON);
       }
       List<VariableDeclaration> variables = new List<VariableDeclaration>();
       variables.add(new VariableDeclaration(null, null, createSyntheticIdentifier(), null, null));
       return new TopLevelVariableDeclaration(commentAndMetadata.comment, commentAndMetadata.metadata, new VariableDeclarationList(null, null, null, returnType, variables), semicolon);
@@ skipping 163 matching lines @@
   Directive parseDirective(CommentAndMetadata commentAndMetadata) {
     if (matches(Keyword.IMPORT)) {
       return parseImportDirective(commentAndMetadata);
     } else if (matches(Keyword.EXPORT)) {
       return parseExportDirective(commentAndMetadata);
     } else if (matches(Keyword.LIBRARY)) {
       return parseLibraryDirective(commentAndMetadata);
     } else if (matches(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 a documentation comment.
    *
    * <pre>
    * documentationComment ::=
    *     multiLineComment?
@@ skipping 248 matching lines @@
           variableList = new VariableDeclarationList(commentAndMetadata.comment, commentAndMetadata.metadata, null, null, variables);
         } else if (isInitializedVariableDeclaration()) {
           variableList = parseVariableDeclarationList(commentAndMetadata);
         } else {
           initialization = parseExpression3();
         }
         if (matches(Keyword.IN)) {
           DeclaredIdentifier loopVariable = null;
           SimpleIdentifier identifier = null;
           if (variableList == null) {
+            // We found: <expression> 'in'
             reportError11(ParserErrorCode.MISSING_VARIABLE_IN_FOR_EACH, []);
           } else {
             NodeList<VariableDeclaration> variables = variableList.variables;
             if (variables.length > 1) {
               reportError11(ParserErrorCode.MULTIPLE_VARIABLES_IN_FOR_EACH, [variables.length.toString()]);
             }
             VariableDeclaration variable = variables[0];
             if (variable.initializer != null) {
               reportError11(ParserErrorCode.INITIALIZED_VARIABLE_IN_FOR_EACH, []);
             }
@@ skipping 83 matching lines @@
         }
         return new BlockFunctionBody(parseBlock());
       } else if (matches2(_NATIVE)) {
         Token nativeToken = andAdvance;
         StringLiteral stringLiteral = null;
         if (matches5(TokenType.STRING)) {
           stringLiteral = parseStringLiteral();
         }
         return new NativeFunctionBody(nativeToken, stringLiteral, expect2(TokenType.SEMICOLON));
       } else {
+        // Invalid function body
         reportError11(emptyErrorCode, []);
         return new EmptyFunctionBody(createSyntheticToken2(TokenType.SEMICOLON));
       }
     } finally {
       _inLoop = wasInLoop;
       _inSwitch = wasInSwitch;
     }
   }
 
   /**
@@ skipping 33 matching lines @@
     } else if (matches5(TokenType.OPEN_PAREN)) {
       reportError11(ParserErrorCode.GETTER_WITH_PARAMETERS, []);
       parseFormalParameterList();
     }
     FunctionBody body;
     if (externalKeyword == null) {
       body = parseFunctionBody(false, ParserErrorCode.MISSING_FUNCTION_BODY, false);
     } else {
       body = new EmptyFunctionBody(expect2(TokenType.SEMICOLON));
     }
+    //    if (!isStatement && matches(TokenType.SEMICOLON)) {
+    //      // 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.
    *
    * <pre>
    * functionDeclarationStatement ::=
    *     functionSignature functionBody
    * </pre>
@@ skipping 57 matching lines @@
     if (matches5(TokenType.LT)) {
       typeParameters = parseTypeParameterList();
     }
     if (matches5(TokenType.SEMICOLON) || matches5(TokenType.EOF)) {
       reportError11(ParserErrorCode.MISSING_TYPEDEF_PARAMETERS, []);
       FormalParameterList parameters = new FormalParameterList(createSyntheticToken2(TokenType.OPEN_PAREN), null, null, null, createSyntheticToken2(TokenType.CLOSE_PAREN));
       Token semicolon = expect2(TokenType.SEMICOLON);
       return new FunctionTypeAlias(commentAndMetadata.comment, commentAndMetadata.metadata, keyword, returnType, name, typeParameters, parameters, semicolon);
     } else if (!matches5(TokenType.OPEN_PAREN)) {
       reportError11(ParserErrorCode.MISSING_TYPEDEF_PARAMETERS, []);
+      // TODO(brianwilkerson) Recover from this error. At the very least we should skip to the start
+      // of the next valid compilation unit member, allowing for the possibility of finding the
+      // typedef parameters before that point.
       return new FunctionTypeAlias(commentAndMetadata.comment, commentAndMetadata.metadata, keyword, returnType, name, typeParameters, new FormalParameterList(createSyntheticToken2(TokenType.OPEN_PAREN), null, null, null, createSyntheticToken2(TokenType.CLOSE_PAREN)), createSyntheticToken2(TokenType.SEMICOLON));
     }
     FormalParameterList parameters = parseFormalParameterList();
     validateFormalParameterList(parameters);
     Token semicolon = expect2(TokenType.SEMICOLON);
     return new FunctionTypeAlias(commentAndMetadata.comment, commentAndMetadata.metadata, keyword, returnType, name, typeParameters, parameters, semicolon);
   }
 
   /**
    * Parse a getter.
@@ skipping 172 matching lines @@
    *
    * @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
    */
   LibraryIdentifier parseLibraryName(ParserErrorCode missingNameError, Token missingNameToken) {
     if (matchesIdentifier()) {
       return parseLibraryIdentifier();
     } else if (matches5(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();
       reportError10(ParserErrorCode.NON_IDENTIFIER_LIBRARY_NAME, string, []);
     } else {
       reportError12(missingNameError, missingNameToken, []);
     }
     List<SimpleIdentifier> components = new List<SimpleIdentifier>();
     components.add(createSyntheticIdentifier());
     return new LibraryIdentifier(components);
   }
 
   /**
    * Parse a list literal.
    *
    * <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 parseListLiteral(Token modifier, TypeArgumentList typeArguments) {
+    // may be empty list literal
     if (matches5(TokenType.INDEX)) {
       BeginToken leftBracket = new BeginToken(TokenType.OPEN_SQUARE_BRACKET, _currentToken.offset);
       Token rightBracket = new Token(TokenType.CLOSE_SQUARE_BRACKET, _currentToken.offset + 1);
       leftBracket.endToken = rightBracket;
       rightBracket.setNext(_currentToken.next);
       leftBracket.setNext(rightBracket);
       _currentToken.previous.setNext(leftBracket);
       _currentToken = _currentToken.next;
       return new ListLiteral(modifier, typeArguments, leftBracket, null, rightBracket);
     }
+    // open
     Token leftBracket = expect2(TokenType.OPEN_SQUARE_BRACKET);
     if (matches5(TokenType.CLOSE_SQUARE_BRACKET)) {
       return new ListLiteral(modifier, typeArguments, leftBracket, null, andAdvance);
     }
     List<Expression> elements = new List<Expression>();
     elements.add(parseExpression3());
     while (optional(TokenType.COMMA)) {
       if (matches5(TokenType.CLOSE_SQUARE_BRACKET)) {
         return new ListLiteral(modifier, typeArguments, leftBracket, elements, andAdvance);
       }
@@ skipping 281 matching lines @@
    *   | tryStatement
    *   | whileStatement
    *   | variableDeclarationList ';'
    *   | expressionStatement
    *   | functionSignature functionBody
    * </pre>
    *
    * @return the non-labeled statement that was parsed
    */
   Statement parseNonLabeledStatement() {
+    // TODO(brianwilkerson) Pass the comment and metadata on where appropriate.
     CommentAndMetadata commentAndMetadata = parseCommentAndMetadata();
     if (matches5(TokenType.OPEN_CURLY_BRACKET)) {
       if (matches4(peek(), TokenType.STRING)) {
         Token afterString = skipStringLiteral(_currentToken.next);
         if (afterString != null && identical(afterString.type, TokenType.COLON)) {
           return new ExpressionStatement(parseExpression3(), expect2(TokenType.SEMICOLON));
         }
       }
       return parseBlock();
     } else if (matches5(TokenType.KEYWORD) && !(_currentToken as KeywordToken).keyword.isPseudoKeyword) {
       Keyword keyword = (_currentToken as KeywordToken).keyword;
+      // TODO(jwren) compute some metrics to figure out a better order for this if-then sequence to optimize performance
       if (identical(keyword, Keyword.ASSERT)) {
         return parseAssertStatement();
       } else if (identical(keyword, Keyword.BREAK)) {
         return parseBreakStatement();
       } else if (identical(keyword, Keyword.CONTINUE)) {
         return parseContinueStatement();
       } else if (identical(keyword, Keyword.DO)) {
         return parseDoStatement();
       } else if (identical(keyword, Keyword.FOR)) {
         return parseForStatement();
@@ skipping 14 matching lines @@
       } else if (identical(keyword, Keyword.VAR) || identical(keyword, Keyword.FINAL)) {
         return parseVariableDeclarationStatement(commentAndMetadata);
       } else if (identical(keyword, Keyword.VOID)) {
         TypeName returnType = parseReturnType();
         if (matchesIdentifier() && matchesAny(peek(), [
             TokenType.OPEN_PAREN,
             TokenType.OPEN_CURLY_BRACKET,
             TokenType.FUNCTION])) {
           return parseFunctionDeclarationStatement2(commentAndMetadata, returnType);
         } else {
+          //
+          // We have found an error of some kind. Try to recover.
+          //
           if (matchesIdentifier()) {
             if (matchesAny(peek(), [TokenType.EQ, TokenType.COMMA, TokenType.SEMICOLON])) {
+              //
+              // We appear to have a variable declaration with a type of "void".
+              //
               reportError10(ParserErrorCode.VOID_VARIABLE, returnType, []);
               return parseVariableDeclarationStatement(commentAndMetadata);
             }
           } else if (matches5(TokenType.CLOSE_CURLY_BRACKET)) {
+            //
+            // We appear to have found an incomplete statement at the end of a block. Parse it as a
+            // variable declaration.
+            //
             return parseVariableDeclarationStatement2(commentAndMetadata, null, returnType);
           }
           reportError11(ParserErrorCode.MISSING_STATEMENT, []);
+          // TODO(brianwilkerson) Recover from this error.
           return new EmptyStatement(createSyntheticToken2(TokenType.SEMICOLON));
         }
       } else if (identical(keyword, Keyword.CONST)) {
         if (matchesAny(peek(), [
             TokenType.LT,
             TokenType.OPEN_CURLY_BRACKET,
             TokenType.OPEN_SQUARE_BRACKET,
             TokenType.INDEX])) {
           return new ExpressionStatement(parseExpression3(), expect2(TokenType.SEMICOLON));
         } else if (matches4(peek(), TokenType.IDENTIFIER)) {
           Token afterType = skipTypeName(peek());
           if (afterType != null) {
             if (matches4(afterType, TokenType.OPEN_PAREN) || (matches4(afterType, TokenType.PERIOD) && matches4(afterType.next, TokenType.IDENTIFIER) && matches4(afterType.next.next, TokenType.OPEN_PAREN))) {
               return new ExpressionStatement(parseExpression3(), expect2(TokenType.SEMICOLON));
             }
           }
         }
         return parseVariableDeclarationStatement(commentAndMetadata);
       } else if (identical(keyword, Keyword.NEW) || identical(keyword, Keyword.TRUE) || identical(keyword, Keyword.FALSE) || identical(keyword, Keyword.NULL) || identical(keyword, Keyword.SUPER) || identical(keyword, Keyword.THIS)) {
         return new ExpressionStatement(parseExpression3(), expect2(TokenType.SEMICOLON));
       } else {
+        //
+        // We have found an error of some kind. Try to recover.
+        //
         reportError11(ParserErrorCode.MISSING_STATEMENT, []);
         return new EmptyStatement(createSyntheticToken2(TokenType.SEMICOLON));
       }
     } else if (matches5(TokenType.SEMICOLON)) {
       return parseEmptyStatement();
     } else if (isInitializedVariableDeclaration()) {
       return parseVariableDeclarationStatement(commentAndMetadata);
     } else if (isFunctionDeclaration()) {
       return parseFunctionDeclarationStatement();
     } else if (matches5(TokenType.CLOSE_CURLY_BRACKET)) {
@@ skipping 198 matching lines @@
       } on FormatException catch (exception) {
       }
       return new IntegerLiteral(token, value);
     } else if (matches5(TokenType.STRING)) {
       return parseStringLiteral();
     } else if (matches5(TokenType.OPEN_CURLY_BRACKET)) {
       return parseMapLiteral(null, null);
     } else if (matches5(TokenType.OPEN_SQUARE_BRACKET) || matches5(TokenType.INDEX)) {
       return parseListLiteral(null, null);
     } else if (matchesIdentifier()) {
+      // TODO(brianwilkerson) The code below was an attempt to recover from an error case, but it
+      // needs to be applied as a recovery only after we know that parsing it as an identifier
+      // doesn't work. Leaving the code as a reminder of how to recover.
+      //      if (isFunctionExpression(peek())) {
+      //        //
+      //        // Function expressions were allowed to have names at one point, but this is now illegal.
+      //        //
+      //        reportError(ParserErrorCode.NAMED_FUNCTION_EXPRESSION, getAndAdvance());
+      //        return parseFunctionExpression();
+      //      }
       return parsePrefixedIdentifier();
     } else if (matches(Keyword.NEW)) {
       return parseNewExpression();
     } else if (matches(Keyword.CONST)) {
       return parseConstExpression();
     } else if (matches5(TokenType.OPEN_PAREN)) {
       if (isFunctionExpression(_currentToken)) {
         return parseFunctionExpression();
       }
       Token leftParenthesis = andAdvance;
       Expression expression = parseExpression3();
       Token rightParenthesis = expect2(TokenType.CLOSE_PAREN);
       return new ParenthesizedExpression(leftParenthesis, expression, rightParenthesis);
     } else if (matches5(TokenType.LT)) {
       return parseListOrMapLiteral(null);
     } else if (matches5(TokenType.QUESTION)) {
       return parseArgumentDefinitionTest();
     } else if (matches(Keyword.VOID)) {
+      //
+      // Recover from having a return type of "void" where a return type is not expected.
+      //
+      // TODO(brianwilkerson) Improve this error message.
       reportError11(ParserErrorCode.UNEXPECTED_TOKEN, [_currentToken.lexeme]);
       advance();
       return parsePrimaryExpression();
     } else if (matches5(TokenType.HASH)) {
       return parseSymbolLiteral();
     } else {
       reportError11(ParserErrorCode.MISSING_IDENTIFIER, []);
       return createSyntheticIdentifier();
     }
   }
@@ skipping 274 matching lines @@
             reportError12(ParserErrorCode.SWITCH_HAS_CASE_AFTER_DEFAULT_CASE, caseKeyword, []);
           }
         } else if (matches(Keyword.DEFAULT)) {
           if (defaultKeyword != null) {
             reportError12(ParserErrorCode.SWITCH_HAS_MULTIPLE_DEFAULT_CASES, peek(), []);
           }
           defaultKeyword = andAdvance;
           Token colon = expect2(TokenType.COLON);
           members.add(new SwitchDefault(labels, defaultKeyword, colon, parseStatements2()));
         } else {
+          // We need to advance, otherwise we could end up in an infinite loop, but this could be a
+          // lot smarter about recovering from the error.
           reportError11(ParserErrorCode.EXPECTED_CASE_OR_DEFAULT, []);
           while (!matches5(TokenType.EOF) && !matches5(TokenType.CLOSE_CURLY_BRACKET) && !matches(Keyword.CASE) && !matches(Keyword.DEFAULT)) {
             advance();
           }
         }
       }
       Token rightBracket = expect2(TokenType.CLOSE_CURLY_BRACKET);
       return new SwitchStatement(keyword, leftParenthesis, expression, rightParenthesis, leftBracket, members, rightBracket);
     } finally {
       _inSwitch = wasInSwitch;
@@ skipping 196 matching lines @@
    *   | incrementOperator assignableExpression
    * </pre>
    *
    * @return the unary expression that was parsed
    */
   Expression parseUnaryExpression() {
     if (matches5(TokenType.MINUS) || matches5(TokenType.BANG) || matches5(TokenType.TILDE)) {
       Token operator = andAdvance;
       if (matches(Keyword.SUPER)) {
         if (matches4(peek(), TokenType.OPEN_SQUARE_BRACKET) || matches4(peek(), TokenType.PERIOD)) {
+          //     "prefixOperator unaryExpression"
+          // --> "prefixOperator postfixExpression"
+          // --> "prefixOperator primary                    selector*"
+          // --> "prefixOperator 'super' assignableSelector selector*"
           return new PrefixExpression(operator, parseUnaryExpression());
         }
         return new PrefixExpression(operator, new SuperExpression(andAdvance));
       }
       return new PrefixExpression(operator, parseUnaryExpression());
     } else if (_currentToken.type.isIncrementOperator) {
       Token operator = andAdvance;
       if (matches(Keyword.SUPER)) {
         if (matches4(peek(), TokenType.OPEN_SQUARE_BRACKET) || matches4(peek(), TokenType.PERIOD)) {
+          // --> "prefixOperator 'super' assignableSelector selector*"
           return new PrefixExpression(operator, parseUnaryExpression());
         }
+        //
+        // Even though it is not valid to use an incrementing operator ('++' or '--') before 'super',
+        // we can (and therefore must) interpret "--super" as semantically equivalent to "-(-super)".
+        // Unfortunately, we cannot do the same for "++super" because "+super" is also not valid.
+        //
         if (identical(operator.type, TokenType.MINUS_MINUS)) {
           int offset = operator.offset;
           Token firstOperator = new Token(TokenType.MINUS, offset);
           Token secondOperator = new Token(TokenType.MINUS, offset + 1);
           secondOperator.setNext(_currentToken);
           firstOperator.setNext(secondOperator);
           operator.previous.setNext(firstOperator);
           return new PrefixExpression(firstOperator, new PrefixExpression(secondOperator, new SuperExpression(andAdvance)));
         } else {
+          // Invalid operator before 'super'
           reportError11(ParserErrorCode.INVALID_OPERATOR_FOR_SUPER, [operator.lexeme]);
           return new PrefixExpression(operator, new SuperExpression(andAdvance));
         }
       }
       return new PrefixExpression(operator, parseAssignableExpression(false));
     } else if (matches5(TokenType.PLUS)) {
       reportError11(ParserErrorCode.MISSING_IDENTIFIER, []);
       return createSyntheticIdentifier();
     }
     return parsePostfixExpression();
@@ skipping 71 matching lines @@
    * <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 parseVariableDeclarationStatement(CommentAndMetadata commentAndMetadata) {
+    //    Token startToken = currentToken;
     VariableDeclarationList variableList = parseVariableDeclarationList(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 = expect2(TokenType.SEMICOLON);
     return new VariableDeclarationStatement(variableList, semicolon);
   }
 
   /**
    * Parse a variable declaration statement.
    *
    * <pre>
    * variableDeclarationStatement ::=
    *     variableDeclarationList ';'
@@ skipping 126 matching lines @@
    * </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 (matches3(startToken, Keyword.FINAL) || matches3(startToken, Keyword.CONST)) {
       Token next = startToken.next;
       if (matchesIdentifier2(next)) {
         Token next2 = next.next;
+        // "Type parameter" or "Type<" or "prefix.Type"
         if (matchesIdentifier2(next2) || matches4(next2, TokenType.LT) || matches4(next2, TokenType.PERIOD)) {
           return skipTypeName(next);
         }
+        // "parameter"
         return next;
       }
     } else if (matches3(startToken, Keyword.VAR)) {
       return startToken.next;
     } else if (matchesIdentifier2(startToken)) {
       Token next = startToken.next;
       if (matchesIdentifier2(next) || matches4(next, TokenType.LT) || matches3(next, Keyword.THIS) || (matches4(next, TokenType.PERIOD) && matchesIdentifier2(next.next) && (matchesIdentifier2(next.next.next) || matches4(next.next.next, TokenType.LT) || matches3(next.next.next, Keyword.THIS)))) {
         return skipReturnType(startToken);
       }
     }
@@ skipping 38 matching lines @@
    * @return the token following the formal parameter list that was parsed
    */
   Token skipFormalParameterList(Token startToken) {
     if (!matches4(startToken, TokenType.OPEN_PAREN)) {
       return null;
     }
     Token next = startToken.next;
     if (matches4(next, TokenType.CLOSE_PAREN)) {
       return next.next;
     }
+    //
+    // Look to see whether the token after the open parenthesis is something that should only occur
+    // at the beginning of a parameter list.
+    //
     if (matchesAny(next, [
         TokenType.AT,
         TokenType.OPEN_SQUARE_BRACKET,
         TokenType.OPEN_CURLY_BRACKET]) || matches3(next, Keyword.VOID) || (matchesIdentifier2(next) && (matchesAny(next.next, [TokenType.COMMA, TokenType.CLOSE_PAREN])))) {
       return skipPastMatchingToken(startToken);
     }
+    //
+    // Look to see whether the first parameter is a function typed parameter without a return type.
+    //
     if (matchesIdentifier2(next) && matches4(next.next, TokenType.OPEN_PAREN)) {
       Token afterParameters = skipFormalParameterList(next.next);
       if (afterParameters != null && (matchesAny(afterParameters, [TokenType.COMMA, TokenType.CLOSE_PAREN]))) {
         return skipPastMatchingToken(startToken);
       }
     }
+    //
+    // Look to see whether the first parameter has a type or is a function typed parameter with a
+    // return type.
+    //
     Token afterType = skipFinalConstVarOrType(next);
     if (afterType == null) {
       return null;
     }
     if (skipSimpleIdentifier(afterType) == null) {
       return null;
     }
     return skipPastMatchingToken(startToken);
   }
 
@@ skipping 99 matching lines @@
    * @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 (identical(type, TokenType.STRING_INTERPOLATION_EXPRESSION) || identical(type, TokenType.STRING_INTERPOLATION_IDENTIFIER)) {
       if (identical(type, TokenType.STRING_INTERPOLATION_EXPRESSION)) {
         token = token.next;
         type = token.type;
+        //
+        // Rather than verify that the following tokens represent a valid expression, we simply skip
+        // tokens until we reach the end of the interpolation, being careful to handle nested string
+        // literals.
+        //
         int bracketNestingLevel = 1;
         while (bracketNestingLevel > 0) {
           if (identical(type, TokenType.EOF)) {
             return null;
           } else if (identical(type, TokenType.OPEN_CURLY_BRACKET)) {
             bracketNestingLevel++;
           } else if (identical(type, TokenType.CLOSE_CURLY_BRACKET)) {
             bracketNestingLevel--;
           } else if (identical(type, TokenType.STRING)) {
             token = skipStringLiteral(token);
@@ skipping 136 matching lines @@
    *     '<' typeParameter (',' typeParameter)* '>'
    * </pre>
    *
    * @param startToken the token at which parsing is to begin
    * @return the token following the type parameter list that was parsed
    */
   Token skipTypeParameterList(Token startToken) {
     if (!matches4(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;
     Token next = startToken.next;
     while (depth > 0) {
       if (matches4(next, TokenType.EOF)) {
         return null;
       } else if (matches4(next, TokenType.LT)) {
         depth++;
       } else if (matches4(next, TokenType.GT)) {
         depth--;
       } else if (matches4(next, TokenType.GT_EQ)) {
@@ skipping 28 matching lines @@
    * @param lexeme the string containing the character(s) to be translated
    * @param index the index of the character to be translated
    * @return the index of the next character to be translated
    */
   int translateCharacter(JavaStringBuilder builder, String lexeme, int index) {
     int currentChar = lexeme.codeUnitAt(index);
     if (currentChar != 0x5C) {
       builder.appendChar(currentChar);
       return index + 1;
     }
+    //
+    // We have found an escape sequence, so we parse the string to determine what kind of escape
+    // sequence and what character to add to the builder.
+    //
     int length = lexeme.length;
     int currentIndex = index + 1;
     if (currentIndex >= length) {
+      // Illegal escape sequence: no char after escape
+      // This cannot actually happen because it would require the escape character to be the last
+      // character in the string, but if it were it would escape the closing quote, leaving the
+      // string unclosed.
+      // reportError(ParserErrorCode.MISSING_CHAR_IN_ESCAPE_SEQUENCE);
       return length;
     }
     currentChar = lexeme.codeUnitAt(currentIndex);
     if (currentChar == 0x6E) {
       builder.appendChar(0xA);
     } else if (currentChar == 0x72) {
       builder.appendChar(0xD);
     } else if (currentChar == 0x66) {
       builder.appendChar(0xC);
     } else if (currentChar == 0x62) {
       builder.appendChar(0x8);
     } else if (currentChar == 0x74) {
       builder.appendChar(0x9);
     } else if (currentChar == 0x76) {
       builder.appendChar(0xB);
     } else if (currentChar == 0x78) {
       if (currentIndex + 2 >= length) {
+        // Illegal escape sequence: not enough hex digits
         reportError11(ParserErrorCode.INVALID_HEX_ESCAPE, []);
         return length;
       }
       int firstDigit = lexeme.codeUnitAt(currentIndex + 1);
       int secondDigit = lexeme.codeUnitAt(currentIndex + 2);
       if (!isHexDigit(firstDigit) || !isHexDigit(secondDigit)) {
+        // Illegal escape sequence: invalid hex digit
         reportError11(ParserErrorCode.INVALID_HEX_ESCAPE, []);
       } else {
         builder.appendChar(((Character.digit(firstDigit, 16) << 4) + Character.digit(secondDigit, 16)));
       }
       return currentIndex + 3;
     } else if (currentChar == 0x75) {
       currentIndex++;
       if (currentIndex >= length) {
+        // Illegal escape sequence: not enough hex digits
         reportError11(ParserErrorCode.INVALID_UNICODE_ESCAPE, []);
         return length;
       }
       currentChar = lexeme.codeUnitAt(currentIndex);
       if (currentChar == 0x7B) {
         currentIndex++;
         if (currentIndex >= length) {
+          // Illegal escape sequence: incomplete escape
           reportError11(ParserErrorCode.INVALID_UNICODE_ESCAPE, []);
           return length;
         }
         currentChar = lexeme.codeUnitAt(currentIndex);
         int digitCount = 0;
         int value = 0;
         while (currentChar != 0x7D) {
           if (!isHexDigit(currentChar)) {
+            // Illegal escape sequence: invalid hex digit
             reportError11(ParserErrorCode.INVALID_UNICODE_ESCAPE, []);
             currentIndex++;
             while (currentIndex < length && lexeme.codeUnitAt(currentIndex) != 0x7D) {
               currentIndex++;
             }
             return currentIndex + 1;
           }
           digitCount++;
           value = (value << 4) + Character.digit(currentChar, 16);
           currentIndex++;
           if (currentIndex >= length) {
+            // Illegal escape sequence: incomplete escape
             reportError11(ParserErrorCode.INVALID_UNICODE_ESCAPE, []);
             return length;
           }
           currentChar = lexeme.codeUnitAt(currentIndex);
         }
         if (digitCount < 1 || digitCount > 6) {
+          // Illegal escape sequence: not enough or too many hex digits
           reportError11(ParserErrorCode.INVALID_UNICODE_ESCAPE, []);
         }
         appendScalarValue(builder, lexeme.substring(index, currentIndex + 1), value, index, currentIndex);
         return currentIndex + 1;
       } else {
         if (currentIndex + 3 >= length) {
+          // Illegal escape sequence: not enough hex digits
           reportError11(ParserErrorCode.INVALID_UNICODE_ESCAPE, []);
           return length;
         }
         int firstDigit = currentChar;
         int secondDigit = lexeme.codeUnitAt(currentIndex + 1);
         int thirdDigit = lexeme.codeUnitAt(currentIndex + 2);
         int fourthDigit = lexeme.codeUnitAt(currentIndex + 3);
         if (!isHexDigit(firstDigit) || !isHexDigit(secondDigit) || !isHexDigit(thirdDigit) || !isHexDigit(fourthDigit)) {
+          // Illegal escape sequence: invalid hex digits
           reportError11(ParserErrorCode.INVALID_UNICODE_ESCAPE, []);
         } else {
           appendScalarValue(builder, lexeme.substring(index, currentIndex + 1), (((((Character.digit(firstDigit, 16) << 4) + Character.digit(secondDigit, 16)) << 4) + Character.digit(thirdDigit, 16)) << 4) + Character.digit(fourthDigit, 16), index, currentIndex + 3);
         }
         return currentIndex + 4;
       }
     } else {
       builder.appendChar(currentChar);
     }
     return currentIndex + 1;
@@ skipping 1537 matching lines @@
    */
   bool isEqual(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);
     }
+    //
+    // Check for a simple transformation caused by entering a period.
+    //
     if (toNode is PrefixedIdentifier) {
       SimpleIdentifier prefix = toNode.prefix;
       if (fromNode.runtimeType == prefix.runtimeType) {
         this._toNode = prefix;
         return fromNode.accept(this);
       }
     } else if (toNode is PropertyAccess) {
       Expression target = toNode.target;
       if (fromNode.runtimeType == target.runtimeType) {
         this._toNode = target;
@@ skipping 68 matching lines @@
     }
     return true;
   }
 }
 
 /**
  * Instances of the class {link ToFormattedSourceVisitor} write a source representation of a visited
  * AST node (and all of it's children) to a writer.
  */
 class ToFormattedSourceVisitor implements ASTVisitor<Object> {
+  static String COMMENTS_KEY = "List of comments before statement";
+
   /**
    * The writer to which the source is to be written.
    */
   PrintWriter _writer;
 
   int _indentLevel = 0;
 
   String _indentString = "";
 
   /**
@@ skipping 171 matching lines @@
     }
     return null;
   }
 
   Object visitCommentReference(CommentReference node) => null;
 
   Object visitCompilationUnit(CompilationUnit node) {
     ScriptTag scriptTag = node.scriptTag;
     NodeList<Directive> directives = node.directives;
     visit(scriptTag);
+    // directives
     String prefix = scriptTag == null ? "" : " ";
     visitList7(prefix, directives, "\n");
     nl();
+    // declarations
     prefix = scriptTag == null && directives.isEmpty ? "" : "\n";
     visitList7(prefix, node.declarations, "\n\n");
     return null;
   }
 
   Object visitConditionalExpression(ConditionalExpression node) {
     visit(node.condition);
     _writer.print(" ? ");
     visit(node.thenExpression);
     _writer.print(" : ");
@@ skipping 693 matching lines @@
 
   void nl() {
     _writer.print("\n");
   }
 
   void nl2() {
     nl();
     indent();
   }
 
+  void printLeadingComments(Statement statement) {
+    List<String> comments = statement.getProperty(COMMENTS_KEY) as List<String>;
+    if (comments == null) {
+      return;
+    }
+    for (String comment in comments) {
+      _writer.print(comment);
+      _writer.print("\n");
+      indent();
+    }
+  }
+
   /**
    * Safely visit the given node.
    *
    * @param node the node to be visited
    */
   void visit(ASTNode node) {
     if (node != null) {
       node.accept(this);
     }
   }
@@ skipping 85 matching lines @@
    *
    * @param prefix the prefix to be printed if the list is not empty
    * @param nodes the nodes to be printed
    * @param separator the separator to be printed between adjacent nodes
    * @param suffix the suffix to be printed if the list is not empty
    */
   void visitList8(String prefix, NodeList<ASTNode> nodes, String separator, String suffix) {
     if (nodes != null) {
       int size = nodes.length;
       if (size != 0) {
+        // prefix
         _writer.print(prefix);
         if (prefix.endsWith("\n")) {
           indent();
         }
+        // nodes
         bool newLineSeparator = separator.endsWith("\n");
         for (int i = 0; i < size; i++) {
           if (i > 0) {
             _writer.print(separator);
             if (newLineSeparator) {
               indent();
             }
           }
-          nodes[i].accept(this);
+          ASTNode node = nodes[i];
+          if (node is Statement) {
+            printLeadingComments(node);
+          }
+          node.accept(this);
         }
+        // suffix
         _writer.print(suffix);
       }
     }
   }
 
   /**
    * Print a list of tokens, separated by the given separator.
    *
    * @param tokens the tokens to be printed
    * @param separator the separator to be printed between adjacent tokens
    */
   void visitList9(List<Token> tokens, String separator) {
     int size = tokens.length;
     for (int i = 0; i < size; i++) {
       if ("\n" == separator) {
         _writer.print("\n");
         indent();
       } else if (i > 0) {
         _writer.print(separator);
       }
       _writer.print(tokens[i].lexeme);
     }
   }
 }