Issue 8742. Preserve leading line comments during java2dart translation.

pkg/analyzer/test/generated/parser_test.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_test;
 
 import 'package:analyzer/src/generated/java_core.dart';
@@ skipping 13 matching lines @@
 
 /**
  * The class `SimpleParserTest` defines parser tests that test individual parsing method. The
  * code fragments should be as minimal as possible in order to test the method, but should not test
  * the interactions between the method under test and other methods.
  *
  * More complex tests should be defined in the class [ComplexParserTest].
  */
 class SimpleParserTest extends ParserTestCase {
   void fail_parseCommentReference_this() {
+    // This fails because we are returning null from the method and asserting that the return value
+    // is not null.
     CommentReference reference = ParserTestCase.parse("parseCommentReference", <Object> ["this", 5], "");
     SimpleIdentifier identifier = EngineTestCase.assertInstanceOf(SimpleIdentifier, reference.identifier);
     JUnitTestCase.assertNotNull(identifier.token);
     JUnitTestCase.assertEquals("a", identifier.name);
     JUnitTestCase.assertEquals(5, identifier.offset);
   }
 
   void test_computeStringValue_emptyInterpolationPrefix() {
     JUnitTestCase.assertEquals("", computeStringValue("'''", true, false));
   }
@@ skipping 781 matching lines @@
     JUnitTestCase.assertNotNull(declaration.classKeyword);
     JUnitTestCase.assertNotNull(declaration.leftBracket);
     JUnitTestCase.assertNotNull(declaration.name);
     EngineTestCase.assertSize(0, declaration.members);
     JUnitTestCase.assertNotNull(declaration.rightBracket);
     JUnitTestCase.assertNotNull(declaration.typeParameters);
     EngineTestCase.assertSize(1, declaration.typeParameters.typeParameters);
   }
 
   void test_parseClassMember_constructor_withInitializers() {
+    // TODO(brianwilkerson) Test other kinds of class members: fields, getters and setters.
     ConstructorDeclaration constructor = ParserTestCase.parse("parseClassMember", <Object> ["C"], "C(_, _\$, this.__) : _a = _ + _\$ {}");
     JUnitTestCase.assertNotNull(constructor.body);
     JUnitTestCase.assertNotNull(constructor.separator);
     JUnitTestCase.assertNull(constructor.externalKeyword);
     JUnitTestCase.assertNull(constructor.constKeyword);
     JUnitTestCase.assertNull(constructor.factoryKeyword);
     JUnitTestCase.assertNull(constructor.name);
     JUnitTestCase.assertNotNull(constructor.parameters);
     JUnitTestCase.assertNull(constructor.period);
     JUnitTestCase.assertNotNull(constructor.returnType);
@@ skipping 1113 matching lines @@
 
   void test_parseExportDirective_show_hide() {
     ExportDirective directive = ParserTestCase.parse("parseExportDirective", <Object> [emptyCommentAndMetadata()], "export 'lib/lib.dart' show B hide A;");
     JUnitTestCase.assertNotNull(directive.keyword);
     JUnitTestCase.assertNotNull(directive.uri);
     EngineTestCase.assertSize(2, directive.combinators);
     JUnitTestCase.assertNotNull(directive.semicolon);
   }
 
   void test_parseExpression_assign() {
+    // TODO(brianwilkerson) Implement more tests for this method.
     AssignmentExpression expression = ParserTestCase.parse5("parseExpression", "x = y", []);
     JUnitTestCase.assertNotNull(expression.leftHandSide);
     JUnitTestCase.assertNotNull(expression.operator);
     JUnitTestCase.assertEquals(TokenType.EQ, expression.operator.type);
     JUnitTestCase.assertNotNull(expression.rightHandSide);
   }
 
   void test_parseExpression_comparison() {
     BinaryExpression expression = ParserTestCase.parse5("parseExpression", "--a.b == c", []);
     JUnitTestCase.assertNotNull(expression.leftOperand);
@@ skipping 24 matching lines @@
     List<Expression> result = ParserTestCase.parse5("parseExpressionList", "1, 2, 3", []);
     EngineTestCase.assertSize(3, result);
   }
 
   void test_parseExpressionList_single() {
     List<Expression> result = ParserTestCase.parse5("parseExpressionList", "1", []);
     EngineTestCase.assertSize(1, result);
   }
 
   void test_parseExpressionWithoutCascade_assign() {
+    // TODO(brianwilkerson) Implement more tests for this method.
     AssignmentExpression expression = ParserTestCase.parse5("parseExpressionWithoutCascade", "x = y", []);
     JUnitTestCase.assertNotNull(expression.leftHandSide);
     JUnitTestCase.assertNotNull(expression.operator);
     JUnitTestCase.assertEquals(TokenType.EQ, expression.operator.type);
     JUnitTestCase.assertNotNull(expression.rightHandSide);
   }
 
   void test_parseExpressionWithoutCascade_comparison() {
     BinaryExpression expression = ParserTestCase.parse5("parseExpressionWithoutCascade", "--a.b == c", []);
     JUnitTestCase.assertNotNull(expression.leftOperand);
@@ skipping 1062 matching lines @@
     ExpressionStatement statement = ParserTestCase.parse5("parseNonLabeledStatement", "const [1, 2];", []);
     JUnitTestCase.assertNotNull(statement.expression);
   }
 
   void test_parseNonLabeledStatement_const_map_empty() {
     ExpressionStatement statement = ParserTestCase.parse5("parseNonLabeledStatement", "const {};", []);
     JUnitTestCase.assertNotNull(statement.expression);
   }
 
   void test_parseNonLabeledStatement_const_map_nonEmpty() {
+    // TODO(brianwilkerson) Implement more tests for this method.
     ExpressionStatement statement = ParserTestCase.parse5("parseNonLabeledStatement", "const {'a' : 1};", []);
     JUnitTestCase.assertNotNull(statement.expression);
   }
 
   void test_parseNonLabeledStatement_const_object() {
     ExpressionStatement statement = ParserTestCase.parse5("parseNonLabeledStatement", "const A();", []);
     JUnitTestCase.assertNotNull(statement.expression);
   }
 
   void test_parseNonLabeledStatement_const_object_named_typeParameters() {
@@ skipping 564 matching lines @@
     String lexeme = "foo";
     SimpleIdentifier identifier = ParserTestCase.parse5("parseSimpleIdentifier", lexeme, []);
     JUnitTestCase.assertNotNull(identifier.token);
     JUnitTestCase.assertEquals(lexeme, identifier.name);
   }
 
   void test_parseSimpleIdentifier1_normalIdentifier() {
   }
 
   void test_parseStatement_functionDeclaration() {
+    // TODO(brianwilkerson) Implement more tests for this method.
     FunctionDeclarationStatement statement = ParserTestCase.parse5("parseStatement", "int f(a, b) {};", []);
     JUnitTestCase.assertNotNull(statement.functionDeclaration);
   }
 
   void test_parseStatement_mulipleLabels() {
     LabeledStatement statement = ParserTestCase.parse5("parseStatement", "l: m: return x;", []);
     EngineTestCase.assertSize(2, statement.labels);
     JUnitTestCase.assertNotNull(statement.statement);
   }
 
@@ skipping 789 matching lines @@
   /**
    * Invoke the method [Parser#isFunctionExpression] with the parser set to the token stream
    * produced by scanning the given source.
    *
    * @param source the source to be scanned to produce the token stream being tested
    * @return the result of invoking the method
    * @throws Exception if the method could not be invoked or throws an exception
    */
   bool isFunctionExpression(String source) {
     GatheringErrorListener listener = new GatheringErrorListener();
+    //
+    // Scan the source.
+    //
     Scanner scanner = new Scanner(null, new CharSequenceReader(new CharSequence(source)), listener);
     Token tokenStream = scanner.tokenize();
+    //
+    // Parse the source.
+    //
     Parser parser = new Parser(null, listener);
     return invokeParserMethodImpl(parser, "isFunctionExpression", <Object> [tokenStream], tokenStream) as bool;
   }
 
   /**
    * Invoke the method [Parser#isInitializedVariableDeclaration] with the parser set to the
    * token stream produced by scanning the given source.
    *
    * @param source the source to be scanned to produce the token stream being tested
    * @return the result of invoking the method
@@ skipping 22 matching lines @@
    * parameter and is given the first token in the scanned source.
    *
    * @param methodName the name of the method that should be invoked
    * @param source the source to be processed by the method
    * @return the result of invoking the method
    * @throws Exception if the method could not be invoked or throws an exception
    * @throws AssertionFailedError if the result is `null`
    */
   Token skip(String methodName, String source) {
     GatheringErrorListener listener = new GatheringErrorListener();
+    //
+    // Scan the source.
+    //
     Scanner scanner = new Scanner(null, new CharSequenceReader(new CharSequence(source)), listener);
     Token tokenStream = scanner.tokenize();
+    //
+    // Parse the source.
+    //
     Parser parser = new Parser(null, listener);
     return invokeParserMethodImpl(parser, methodName, <Object> [tokenStream], tokenStream) as Token;
   }
 
   static dartSuite() {
     _ut.group('SimpleParserTest', () {
       _ut.test('test_Parser', () {
         final __test = new SimpleParserTest();
         runJUnitTest(__test, __test.test_Parser);
       });
@@ skipping 2225 matching lines @@
   }
 
   void test_additiveExpression_super() {
     BinaryExpression expression = ParserTestCase.parseExpression("super + y - z", []);
     EngineTestCase.assertInstanceOf(BinaryExpression, expression.leftOperand);
   }
 
   void test_assignableExpression_arguments_normal_chain() {
     PropertyAccess propertyAccess1 = ParserTestCase.parseExpression("a(b)(c).d(e).f", []);
     JUnitTestCase.assertEquals("f", propertyAccess1.propertyName.name);
+    //
+    // a(b)(c).d(e)
+    //
     MethodInvocation invocation2 = EngineTestCase.assertInstanceOf(MethodInvocation, propertyAccess1.target);
     JUnitTestCase.assertEquals("d", invocation2.methodName.name);
     ArgumentList argumentList2 = invocation2.argumentList;
     JUnitTestCase.assertNotNull(argumentList2);
     EngineTestCase.assertSize(1, argumentList2.arguments);
+    //
+    // a(b)(c)
+    //
     FunctionExpressionInvocation invocation3 = EngineTestCase.assertInstanceOf(FunctionExpressionInvocation, invocation2.target);
     ArgumentList argumentList3 = invocation3.argumentList;
     JUnitTestCase.assertNotNull(argumentList3);
     EngineTestCase.assertSize(1, argumentList3.arguments);
+    //
+    // a(b)
+    //
     MethodInvocation invocation4 = EngineTestCase.assertInstanceOf(MethodInvocation, invocation3.function);
     JUnitTestCase.assertEquals("a", invocation4.methodName.name);
     ArgumentList argumentList4 = invocation4.argumentList;
     JUnitTestCase.assertNotNull(argumentList4);
     EngineTestCase.assertSize(1, argumentList4.arguments);
   }
 
   void test_assignmentExpression_compound() {
     AssignmentExpression expression = ParserTestCase.parseExpression("x = y = 0", []);
     EngineTestCase.assertInstanceOf(SimpleIdentifier, expression.leftHandSide);
@@ skipping 663 matching lines @@
    * @param methodName the name of the method that should be invoked
    * @param objects the values of the arguments to the method
    * @param source the source to be processed by the parse method
    * @param listener the error listener that will be used for both scanning and parsing
    * @return the result of invoking the method
    * @throws Exception if the method could not be invoked or throws an exception
    * @throws AssertionFailedError if the result is `null` or the errors produced while
    *           scanning and parsing the source do not match the expected errors
    */
   static Object invokeParserMethod(String methodName, List<Object> objects, String source, GatheringErrorListener listener) {
+    //
+    // Scan the source.
+    //
     Scanner scanner = new Scanner(null, new CharSequenceReader(new CharSequence(source)), listener);
     Token tokenStream = scanner.tokenize();
     listener.setLineInfo(new TestSource(), scanner.lineStarts);
+    //
+    // Parse the source.
+    //
     Parser parser = new Parser(null, listener);
     parser.parseFunctionBodies = _parseFunctionBodies;
     Object result = invokeParserMethodImpl(parser, methodName, objects, tokenStream);
+    //
+    // Partially test the results.
+    //
     if (!listener.hasErrors()) {
       JUnitTestCase.assertNotNull(result);
     }
     return result;
   }
 
   /**
    * Invoke a method in [Parser]. The method is assumed to have no arguments.
    *
    * The given source is scanned and the parser is initialized to start with the first token in the
@@ skipping 1689 matching lines @@
       _ut.test('test_typedef_eof', () {
         final __test = new RecoveryParserTest();
         runJUnitTest(__test, __test.test_typedef_eof);
       });
     });
   }
 }
 
 class IncrementalParserTest extends EngineTestCase {
   void test_delete_everything() {
+    // "f() => a + b;"
+    // ""
     assertParse("", "f() => a + b;", "", "");
   }
 
   void test_delete_identifier_beginning() {
+    // "f() => abs + b;"
+    // "f() => s + b;"
     assertParse("f() => ", "ab", "", "s + b;");
   }
 
   void test_delete_identifier_end() {
+    // "f() => abs + b;"
+    // "f() => a + b;"
     assertParse("f() => a", "bs", "", " + b;");
   }
 
   void test_delete_identifier_middle() {
+    // "f() => abs + b;"
+    // "f() => as + b;"
     assertParse("f() => a", "b", "", "s + b;");
   }
 
   void test_delete_mergeTokens() {
+    // "f() => a + b + c;"
+    // "f() => ac;"
     assertParse("f() => a", " + b + ", "", "c;");
   }
 
   void test_insert_afterIdentifier1() {
+    // "f() => a + b;"
+    // "f() => abs + b;"
     assertParse("f() => a", "", "bs", " + b;");
   }
 
   void test_insert_afterIdentifier2() {
+    // "f() => a + b;"
+    // "f() => a + bar;"
     assertParse("f() => a + b", "", "ar", ";");
   }
 
   void test_insert_beforeIdentifier1() {
+    // "f() => a + b;"
+    // "f() => xa + b;"
     assertParse("f() => ", "", "x", "a + b;");
   }
 
   void test_insert_beforeIdentifier2() {
+    // "f() => a + b;"
+    // "f() => a + xb;"
     assertParse("f() => a + ", "", "x", "b;");
   }
 
   void test_insert_convertOneFunctionToTwo() {
+    // "f() {}"
+    // "f() => 0; g() {}"
     assertParse("f()", "", " => 0; g()", " {}");
   }
 
   void test_insert_end() {
+    // "class A {}"
+    // "class A {} class B {}"
     assertParse("class A {}", "", " class B {}", "");
   }
 
   void test_insert_insideIdentifier() {
+    // "f() => cob;"
+    // "f() => cow.b;"
     assertParse("f() => co", "", "w.", "b;");
   }
 
   void test_insert_newIdentifier1() {
+    // "f() => a; c;"
+    // "f() => a; b c;"
     assertParse("f() => a;", "", " b", " c;");
   }
 
   void test_insert_newIdentifier2() {
+    // "f() => a;  c;"
+    // "f() => a;b  c;"
     assertParse("f() => a;", "", "b", "  c;");
   }
 
   void test_insert_newIdentifier3() {
+    // "/** A simple function. */ f() => a; c;"
+    // "/** A simple function. */ f() => a; b c;"
     assertParse("/** A simple function. */ f() => a;", "", " b", " c;");
   }
 
   void test_insert_newIdentifier4() {
+    // "/** An [A]. */ class A {} class B { m() { return 1; } }"
+    // "/** An [A]. */ class A {} class B { m() { return 1 + 2; } }"
     assertParse("/** An [A]. */ class A {} class B { m() { return 1", "", " + 2", "; } }");
   }
 
   void test_insert_period() {
+    // "f() => a + b;"
+    // "f() => a + b.;"
     assertParse("f() => a + b", "", ".", ";");
   }
 
   void test_insert_period_betweenIdentifiers1() {
+    // "f() => a b;"
+    // "f() => a. b;"
     assertParse("f() => a", "", ".", " b;");
   }
 
   void test_insert_period_betweenIdentifiers2() {
+    // "f() => a b;"
+    // "f() => a .b;"
     assertParse("f() => a ", "", ".", "b;");
   }
 
   void test_insert_period_betweenIdentifiers3() {
+    // "f() => a  b;"
+    // "f() => a . b;"
     assertParse("f() => a ", "", ".", " b;");
   }
 
   void test_insert_period_insideExistingIdentifier() {
+    // "f() => ab;"
+    // "f() => a.b;"
     assertParse("f() => a", "", ".", "b;");
   }
 
   void test_insert_periodAndIdentifier() {
+    // "f() => a + b;"
+    // "f() => a + b.x;"
     assertParse("f() => a + b", "", ".x", ";");
   }
 
   void test_insert_simpleToComplexExression() {
+    // "/** An [A]. */ class A {} class B { m() => 1; }"
+    // "/** An [A]. */ class A {} class B { m() => 1 + 2; }"
     assertParse("/** An [A]. */ class A {} class B { m() => 1", "", " + 2", "; }");
   }
 
   void test_insert_whitespace_end() {
+    // "f() => a + b;"
+    // "f() => a + b; "
     assertParse("f() => a + b;", "", " ", "");
   }
 
   void test_insert_whitespace_end_multiple() {
+    // "f() => a + b;"
+    // "f() => a + b;  "
     assertParse("f() => a + b;", "", "  ", "");
   }
 
   void test_insert_whitespace_middle() {
+    // "f() => a + b;"
+    // "f() => a  + b;"
     assertParse("f() => a", "", " ", " + b;");
   }
 
   void test_replace_identifier_beginning() {
+    // "f() => bell + b;"
+    // "f() => fell + b;"
     assertParse("f() => ", "b", "f", "ell + b;");
   }
 
   void test_replace_identifier_end() {
+    // "f() => bell + b;"
+    // "f() => belt + b;"
     assertParse("f() => bel", "l", "t", " + b;");
   }
 
   void test_replace_identifier_middle() {
+    // "f() => first + b;"
+    // "f() => frost + b;"
     assertParse("f() => f", "ir", "ro", "st + b;");
   }
 
   void test_replace_multiple_partialFirstAndLast() {
+    // "f() => aa + bb;"
+    // "f() => ab * ab;"
     assertParse("f() => a", "a + b", "b * a", "b;");
   }
 
   void test_replace_operator_oneForMany() {
+    // "f() => a + b;"
+    // "f() => a * c - b;"
     assertParse("f() => a ", "+", "* c -", " b;");
   }
 
   void test_replace_operator_oneForOne() {
+    // "f() => a + b;"
+    // "f() => a * b;"
     assertParse("f() => a ", "+", "*", " b;");
   }
 
   /**
    * Given a description of the original and modified contents, perform an incremental scan of the
    * two pieces of text.
    *
    * @param prefix the unchanged text before the edit region
    * @param removed the text that was removed from the original contents
    * @param added the text that was added to the modified contents
    * @param suffix the unchanged text after the edit region
    */
   void assertParse(String prefix, String removed, String added, String suffix) {
+    //
+    // Compute the information needed to perform the test.
+    //
     String originalContents = "${prefix}${removed}${suffix}";
     String modifiedContents = "${prefix}${added}${suffix}";
     int replaceStart = prefix.length;
     Source source = new TestSource();
+    //
+    // Parse the original contents.
+    //
     GatheringErrorListener originalListener = new GatheringErrorListener();
     Scanner originalScanner = new Scanner(source, new CharSequenceReader(new CharSequence(originalContents)), originalListener);
     Token originalTokens = originalScanner.tokenize();
     JUnitTestCase.assertNotNull(originalTokens);
     Parser originalParser = new Parser(source, originalListener);
     CompilationUnit originalUnit = originalParser.parseCompilationUnit(originalTokens);
     JUnitTestCase.assertNotNull(originalUnit);
+    //
+    // Parse the modified contents.
+    //
     GatheringErrorListener modifiedListener = new GatheringErrorListener();
     Scanner modifiedScanner = new Scanner(source, new CharSequenceReader(new CharSequence(modifiedContents)), modifiedListener);
     Token modifiedTokens = modifiedScanner.tokenize();
     JUnitTestCase.assertNotNull(modifiedTokens);
     Parser modifiedParser = new Parser(source, modifiedListener);
     CompilationUnit modifiedUnit = modifiedParser.parseCompilationUnit(modifiedTokens);
     JUnitTestCase.assertNotNull(modifiedUnit);
+    //
+    // Incrementally parse the modified contents.
+    //
     GatheringErrorListener incrementalListener = new GatheringErrorListener();
     IncrementalScanner incrementalScanner = new IncrementalScanner(source, new CharSequenceReader(new CharSequence(modifiedContents)), incrementalListener);
     Token incrementalTokens = incrementalScanner.rescan(originalTokens, replaceStart, removed.length, added.length);
     JUnitTestCase.assertNotNull(incrementalTokens);
     IncrementalParser incrementalParser = new IncrementalParser(source, incrementalScanner.tokenMap, incrementalListener);
     CompilationUnit incrementalUnit = incrementalParser.reparse(originalUnit, incrementalScanner.leftToken, incrementalScanner.rightToken, replaceStart, prefix.length + removed.length);
     JUnitTestCase.assertNotNull(incrementalUnit);
+    //
+    // Validate that the results of the incremental parse are the same as the full parse of the
+    // modified source.
+    //
     JUnitTestCase.assertTrue(ASTComparator.equals4(modifiedUnit, incrementalUnit));
   }
 
   static dartSuite() {
     _ut.group('IncrementalParserTest', () {
       _ut.test('test_delete_everything', () {
         final __test = new IncrementalParserTest();
         runJUnitTest(__test, __test.test_delete_everything);
       });
       _ut.test('test_delete_identifier_beginning', () {
@@ skipping 123 matching lines @@
     });
   }
 }
 
 /**
  * The class `ErrorParserTest` defines parser tests that test the parsing of code to ensure
  * that errors are correctly reported, and in some cases, not reported.
  */
 class ErrorParserTest extends ParserTestCase {
   void fail_expectedListOrMapLiteral() {
+    // It isn't clear that this test can ever pass. The parser is currently create a synthetic list
+    // literal in this case, but isSynthetic() isn't overridden for ListLiteral. The problem is that
+    // the synthetic list literals that are being created are not always zero length (because they
+    // could have type parameters), which violates the contract of isSynthetic().
     TypedLiteral literal = ParserTestCase.parse4("parseListOrMapLiteral", <Object> [null], "1", [ParserErrorCode.EXPECTED_LIST_OR_MAP_LITERAL]);
     JUnitTestCase.assertTrue(literal.isSynthetic);
   }
 
   void fail_illegalAssignmentToNonAssignable_superAssigned() {
+    // TODO(brianwilkerson) When this test starts to pass, remove the test
+    // test_illegalAssignmentToNonAssignable_superAssigned.
     ParserTestCase.parseExpression("super = x;", [ParserErrorCode.ILLEGAL_ASSIGNMENT_TO_NON_ASSIGNABLE]);
   }
 
   void fail_invalidCommentReference__new_nonIdentifier() {
+    // This test fails because the method parseCommentReference returns null.
     ParserTestCase.parse4("parseCommentReference", <Object> ["new 42", 0], "", [ParserErrorCode.INVALID_COMMENT_REFERENCE]);
   }
 
   void fail_invalidCommentReference__new_tooMuch() {
     ParserTestCase.parse4("parseCommentReference", <Object> ["new a.b.c.d", 0], "", [ParserErrorCode.INVALID_COMMENT_REFERENCE]);
   }
 
   void fail_invalidCommentReference__nonNew_nonIdentifier() {
+    // This test fails because the method parseCommentReference returns null.
     ParserTestCase.parse4("parseCommentReference", <Object> ["42", 0], "", [ParserErrorCode.INVALID_COMMENT_REFERENCE]);
   }
 
   void fail_invalidCommentReference__nonNew_tooMuch() {
     ParserTestCase.parse4("parseCommentReference", <Object> ["a.b.c.d", 0], "", [ParserErrorCode.INVALID_COMMENT_REFERENCE]);
   }
 
   void fail_missingClosingParenthesis() {
+    // It is possible that it is not possible to generate this error (that it's being reported in
+    // code that cannot actually be reached), but that hasn't been proven yet.
     ParserTestCase.parse5("parseFormalParameterList", "(int a, int b ;", [ParserErrorCode.MISSING_CLOSING_PARENTHESIS]);
   }
 
   void fail_missingFunctionParameters_local_nonVoid_block() {
+    // The parser does not recognize this as a function declaration, so it tries to parse it as an
+    // expression statement. It isn't clear what the best error message is in this case.
     ParserTestCase.parseStatement("int f { return x;}", [ParserErrorCode.MISSING_FUNCTION_PARAMETERS]);
   }
 
   void fail_missingFunctionParameters_local_nonVoid_expression() {
+    // The parser does not recognize this as a function declaration, so it tries to parse it as an
+    // expression statement. It isn't clear what the best error message is in this case.
     ParserTestCase.parseStatement("int f => x;", [ParserErrorCode.MISSING_FUNCTION_PARAMETERS]);
   }
 
   void fail_namedFunctionExpression() {
     Expression expression = ParserTestCase.parse5("parsePrimaryExpression", "f() {}", [ParserErrorCode.NAMED_FUNCTION_EXPRESSION]);
     EngineTestCase.assertInstanceOf(FunctionExpression, expression);
   }
 
   void fail_unexpectedToken_invalidPostfixExpression() {
+    // Note: this might not be the right error to produce, but some error should be produced
     ParserTestCase.parseExpression("f()++", [ParserErrorCode.UNEXPECTED_TOKEN]);
   }
 
   void fail_varAndType_local() {
+    // This is currently reporting EXPECTED_TOKEN for a missing semicolon, but this would be a
+    // better error message.
     ParserTestCase.parseStatement("var int x;", [ParserErrorCode.VAR_AND_TYPE]);
   }
 
   void fail_varAndType_parameter() {
+    // This is currently reporting EXPECTED_TOKEN for a missing semicolon, but this would be a
+    // better error message.
     ParserTestCase.parse5("parseFormalParameterList", "(var int x)", [ParserErrorCode.VAR_AND_TYPE]);
   }
 
   void test_abstractClassMember_constructor() {
     ParserTestCase.parse4("parseClassMember", <Object> ["C"], "abstract C.c();", [ParserErrorCode.ABSTRACT_CLASS_MEMBER]);
   }
 
   void test_abstractClassMember_field() {
     ParserTestCase.parse4("parseClassMember", <Object> ["C"], "abstract C f;", [ParserErrorCode.ABSTRACT_CLASS_MEMBER]);
   }
@@ skipping 394 matching lines @@
 
   void test_getterInFunction_expression() {
     ParserTestCase.parseStatement("get x => _x;", [ParserErrorCode.GETTER_IN_FUNCTION]);
   }
 
   void test_getterWithParameters() {
     ParserTestCase.parse4("parseClassMember", <Object> ["C"], "int get x() {}", [ParserErrorCode.GETTER_WITH_PARAMETERS]);
   }
 
   void test_illegalAssignmentToNonAssignable_superAssigned() {
+    // TODO(brianwilkerson) When the test fail_illegalAssignmentToNonAssignable_superAssigned starts
+    // to pass, remove this test (there should only be one error generated, but we're keeping this
+    // test until that time so that we can catch other forms of regressions).
     ParserTestCase.parseExpression("super = x;", [
         ParserErrorCode.MISSING_ASSIGNABLE_SELECTOR,
         ParserErrorCode.ILLEGAL_ASSIGNMENT_TO_NON_ASSIGNABLE]);
   }
 
   void test_implementsBeforeExtends() {
     ParserTestCase.parseCompilationUnit("class A implements B extends C {}", [ParserErrorCode.IMPLEMENTS_BEFORE_EXTENDS]);
   }
 
   void test_implementsBeforeWith() {
@@ skipping 1706 matching lines @@
   'validateModifiersForTopLevelFunction_1': new MethodTrampoline(1, (Parser target, arg0) => target.validateModifiersForTopLevelFunction(arg0)),
   'validateModifiersForTopLevelVariable_1': new MethodTrampoline(1, (Parser target, arg0) => target.validateModifiersForTopLevelVariable(arg0)),
   'validateModifiersForTypedef_1': new MethodTrampoline(1, (Parser target, arg0) => target.validateModifiersForTypedef(arg0)),};
 
 
 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);
 }