Add support for documentation comments to most of AstBuilder.

pkg/analyzer/test/generated/parser_test.dart

Index: pkg/analyzer/test/generated/parser_test.dart
diff --git a/pkg/analyzer/test/generated/parser_test.dart b/pkg/analyzer/test/generated/parser_test.dart
index 6520dea361f5584e34a93c47af32d24c1838f3e5..52faa8f515cb9fc67b56ba9c0bb3033661dc3fe8 100644
--- a/pkg/analyzer/test/generated/parser_test.dart
+++ b/pkg/analyzer/test/generated/parser_test.dart
@@ -354,6 +354,12 @@ abstract class ClassMemberParserTestMixin implements AbstractParserTestCase {
         AwaitExpression, (expression as BinaryExpression).rightOperand);
   }
 
+  void test_parseClassMember_constructor_withDocComment() {
+    createParser('/// Doc\nC();');
+    var constructor = parser.parseClassMember('C') as ConstructorDeclaration;

[ahe, 2017/03/09 13:56:01]

Why don't you just put the type on the variable?

[Paul Berry, 2017/03/09 16:42:04]

Two reasons:

1. it makes the downcast obvious.  A casual reader might see
"ConstructorDeclaration constructor = parser.parseClassMember('C');" and fail to
notice that the assignment might fail if parseClassMember returns the wrong
type.

2. it guarantees that if parseClassMember returns the wrong type, we will get a
test failure regardless of whether the test is running in checked mode.

+    expectCommentText(constructor.documentationComment, '/// Doc');
+  }
+
   void test_parseClassMember_constructor_withInitializers() {
     // TODO(brianwilkerson) Test other kinds of class members: fields, getters
     // and setters.
@@ -1232,6 +1238,18 @@ abstract class ClassMemberParserTestMixin implements AbstractParserTestCase {
     expect(method.propertyKeyword, isNotNull);
     expect((method.returnType as TypeName).name.name, 'T');
   }
+
+  void test_simpleFormalParameter_withDocComment() {
+    createParser('''
+int f(
+    /// Doc
+    int x) {}
+''');
+    var function = parseFullCompilationUnitMember() as FunctionDeclaration;
+    var parameter = function.functionExpression.parameters.parameters[0]
+        as NormalFormalParameter;
+    expectCommentText(parameter.documentationComment, '/// Doc');
+  }
 }
 
 /**
@@ -7250,6 +7268,11 @@ abstract class FormalParameterParserTestMixin
     expect(parameterList.parameters, hasLength(0));
   }
 
+  void test_parseNormalFormalParameter_field_function_withDocComment() {
+    var parameter = parseNormalFormalParameter('/// Doc\nthis.f()');
+    expectCommentText(parameter.documentationComment, '/// Doc');
+  }
+
   void test_parseNormalFormalParameter_field_noType() {
     NormalFormalParameter parameter = parseNormalFormalParameter('this.a');
     expect(parameter, isNotNull);
@@ -7286,6 +7309,11 @@ abstract class FormalParameterParserTestMixin
     expect(fieldParameter.parameters, isNull);
   }
 
+  void test_parseNormalFormalParameter_field_withDocComment() {
+    var parameter = parseNormalFormalParameter('/// Doc\nthis.a');
+    expectCommentText(parameter.documentationComment, '/// Doc');
+  }
+
   void test_parseNormalFormalParameter_function_named() {
     ParameterKind kind = ParameterKind.NAMED;
     var defaultParameter =
@@ -7524,6 +7552,12 @@ abstract class FormalParameterParserTestMixin
     expect(functionParameter.question, isNotNull);
   }
 
+  void test_parseNormalFormalParameter_function_withDocComment() {
+    var parameter = parseFormalParameter('/// Doc\nf()', ParameterKind.REQUIRED)
+        as FunctionTypedFormalParameter;
+    expectCommentText(parameter.documentationComment, '/// Doc');
+  }
+
   void test_parseNormalFormalParameter_simple_const_noType() {
     NormalFormalParameter parameter = parseNormalFormalParameter('const a');
     expect(parameter, isNotNull);
@@ -13048,6 +13082,12 @@ abstract class TopLevelParserTestMixin implements AbstractParserTestCase {
         "import 'import1_lib.dart' show hide, show hide ugly;");
   }
 
+  void test_import_withDocComment() {
+    var compilationUnit = parseCompilationUnit('/// Doc\nimport "foo.dart";');
+    var importDirective = compilationUnit.directives[0];
+    expectCommentText(importDirective.documentationComment, '/// Doc');
+  }
+
   void test_parseClassDeclaration_abstract() {
     createParser('abstract class A {}');
     CompilationUnitMember member = parseFullCompilationUnitMember();
@@ -13271,6 +13311,18 @@ abstract class TopLevelParserTestMixin implements AbstractParserTestCase {
     expect(declaration.typeParameters.typeParameters, hasLength(1));
   }
 
+  void test_parseClassDeclaration_withDocumentationComment() {
+    createParser('/// Doc\nclass C {}');
+    var classDeclaration = parseFullCompilationUnitMember() as ClassDeclaration;
+    expectCommentText(classDeclaration.documentationComment, '/// Doc');
+  }
+
+  void test_parseClassTypeAlias_withDocumentationComment() {
+    createParser('/// Doc\nclass C = D with E;');
+    var classTypeAlias = parseFullCompilationUnitMember() as ClassTypeAlias;
+    expectCommentText(classTypeAlias.documentationComment, '/// Doc');
+  }
+
   void test_parseCompilationUnit_abstractAsPrefix_parameterized() {
     createParser('abstract<dynamic> _abstract = new abstract.A();');
     CompilationUnit unit = parser.parseCompilationUnit2();
@@ -13741,6 +13793,12 @@ abstract class TopLevelParserTestMixin implements AbstractParserTestCase {
     expect(typeAlias.parameters.parameters, hasLength(0));
   }
 
+  void test_parseCompilationUnitMember_typedef_withDocComment() {
+    createParser('/// Doc\ntypedef F();');
+    var typeAlias = parseFullCompilationUnitMember() as FunctionTypeAlias;
+    expectCommentText(typeAlias.documentationComment, '/// Doc');
+  }
+
   void test_parseCompilationUnitMember_typedVariable() {
     createParser('int x = 0;');
     CompilationUnitMember member = parseFullCompilationUnitMember();
@@ -13766,6 +13824,13 @@ abstract class TopLevelParserTestMixin implements AbstractParserTestCase {
     expect(declaration.variables.keyword.lexeme, 'var');
   }
 
+  void test_parseCompilationUnitMember_variable_withDocumentationComment() {
+    createParser('/// Doc\nvar x = 0;');
+    var declaration =
+        parseFullCompilationUnitMember() as TopLevelVariableDeclaration;
+    expectCommentText(declaration.documentationComment, '/// Doc');
+  }
+
   void test_parseCompilationUnitMember_variableGet() {
     createParser('String get = null;');
     CompilationUnitMember member = parseFullCompilationUnitMember();
@@ -13801,6 +13866,12 @@ abstract class TopLevelParserTestMixin implements AbstractParserTestCase {
     expect(exportDirective.semicolon, isNotNull);
   }
 
+  void test_parseDirective_export_withDocComment() {
+    createParser("/// Doc\nexport 'foo.dart';");
+    var directive = parseFullDirective() as ExportDirective;
+    expectCommentText(directive.documentationComment, '/// Doc');
+  }
+
   void test_parseDirective_import() {
     createParser("import 'lib/lib.dart';");
     Directive directive = parseFullDirective();
@@ -13852,6 +13923,12 @@ abstract class TopLevelParserTestMixin implements AbstractParserTestCase {
     expect(lib.name.components[2].name, 'c');
   }
 
+  void test_parseDirective_library_withDocumentationComment() {
+    createParser('/// Doc\nlibrary l;');
+    var directive = parseFullDirective() as LibraryDirective;
+    expectCommentText(directive.documentationComment, '/// Doc');
+  }
+
   void test_parseDirective_part() {
     createParser("part 'lib/lib.dart';");
     Directive directive = parseFullDirective();
@@ -13888,6 +13965,18 @@ abstract class TopLevelParserTestMixin implements AbstractParserTestCase {
     expect(partOf.libraryName.components[2].name, 'c');
   }
 
+  void test_parseDirective_part_of_withDocumentationComment() {
+    createParser('/// Doc\npart of a;');
+    var partOf = parseFullDirective() as PartOfDirective;
+    expectCommentText(partOf.documentationComment, '/// Doc');
+  }
+
+  void test_parseDirective_part_withDocumentationComment() {
+    createParser("/// Doc\npart 'lib.dart';");
+    var directive = parseFullDirective() as PartDirective;
+    expectCommentText(directive.documentationComment, '/// Doc');
+  }
+
   void test_parseDirective_partOf() {
     createParser("part of l;");
     Directive directive = parseFullDirective();
@@ -13984,6 +14073,23 @@ abstract class TopLevelParserTestMixin implements AbstractParserTestCase {
     expect(declaration.rightBracket, isNotNull);
   }
 
+  void test_parseEnumDeclaration_withDocComment_onEnum() {
+    createParser('/// Doc\nenum E {ONE}');
+    var declaration = parseFullCompilationUnitMember() as EnumDeclaration;
+    expectCommentText(declaration.documentationComment, '/// Doc');
+  }
+
+  void test_parseEnumDeclaration_withDocComment_onValue() {
+    createParser('''
+enum E {
+  /// Doc
+  ONE
+}''');
+    var declaration = parseFullCompilationUnitMember() as EnumDeclaration;
+    var value = declaration.constants[0];
+    expectCommentText(value.documentationComment, '/// Doc');
+  }
+
   void test_parseExportDirective_configuration_multiple() {
     createParser("export 'lib/lib.dart' if (a) 'b.dart' if (c) 'd.dart';");
     ExportDirective directive = parseFullDirective();
@@ -14618,4 +14724,10 @@ abstract class TopLevelParserTestMixin implements AbstractParserTestCase {
     expect(functionType.returnType, isNotNull);
     expect(functionType.typeParameters, isNull);
   }
+
+  void test_parseTypeAlias_genericFunction_withDocComment() {
+    createParser('/// Doc\ntypedef F = bool Function();');
+    var typeAlias = parseFullCompilationUnitMember() as GenericTypeAlias;
+    expectCommentText(typeAlias.documentationComment, '/// Doc');
+  }
 }