Add support for documentation comments to most of AstBuilder.

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.
 
 library analyzer.test.generated.parser_test;
 
 import 'package:analyzer/dart/ast/ast.dart';
 import 'package:analyzer/dart/ast/standard_ast_factory.dart';
 import 'package:analyzer/dart/ast/token.dart';
 import 'package:analyzer/dart/ast/visitor.dart';
@@ skipping 336 matching lines @@
         (obj) => obj is ReturnStatement, ReturnStatement, statement);
     Expression expression = (statement as ReturnStatement).expression;
     EngineTestCase.assertInstanceOf(
         (obj) => obj is BinaryExpression, BinaryExpression, expression);
     EngineTestCase.assertInstanceOf((obj) => obj is AwaitExpression,
         AwaitExpression, (expression as BinaryExpression).leftOperand);
     EngineTestCase.assertInstanceOf((obj) => obj is AwaitExpression,
         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.
     createParser('C(_, _\$, this.__) : _a = _ + _\$ {}');
     ClassMember member = parser.parseClassMember('C');
     expect(member, isNotNull);
     assertNoErrors();
     expect(member, new isInstanceOf<ConstructorDeclaration>());
     ConstructorDeclaration constructor = member;
     expect(constructor.body, isNotNull);
@@ skipping 858 matching lines @@
     expectCommentText(method.documentationComment, '/// Doc');
     expect(method.externalKeyword, isNull);
     expect(method.modifierKeyword.lexeme, 'static');
     expect(method.name, isNotNull);
     expect(method.operatorKeyword, isNull);
     expect(method.typeParameters, isNull);
     expect(method.parameters, isNotNull);
     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');
+  }
 }
 
 /**
  * Tests of the analyzer parser based on [ComplexParserTestMixin].
  */
 @reflectiveTest
 class ComplexParserTest extends ParserTestCase with ComplexParserTestMixin {}
 
 /**
  * The class `ComplexParserTest` defines parser tests that test the parsing of more complex
@@ skipping 5998 matching lines @@
     expect(parameter, new isInstanceOf<FieldFormalParameter>());
     FieldFormalParameter fieldParameter = parameter;
     expect(fieldParameter.keyword, isNull);
     expect(fieldParameter.type, isNull);
     expect(fieldParameter.identifier, isNotNull);
     FormalParameterList parameterList = fieldParameter.parameters;
     expect(parameterList, isNotNull);
     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);
     assertNoErrors();
     expect(parameter, new isInstanceOf<FieldFormalParameter>());
     FieldFormalParameter fieldParameter = parameter;
     expect(fieldParameter.keyword, isNull);
     expect(fieldParameter.type, isNull);
     expect(fieldParameter.identifier, isNotNull);
     expect(fieldParameter.parameters, isNull);
@@ skipping 16 matching lines @@
     expect(parameter, isNotNull);
     assertNoErrors();
     expect(parameter, new isInstanceOf<FieldFormalParameter>());
     FieldFormalParameter fieldParameter = parameter;
     expect(fieldParameter.keyword, isNotNull);
     expect(fieldParameter.type, isNull);
     expect(fieldParameter.identifier, isNotNull);
     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 =
         parseFormalParameter('a() : null', kind) as DefaultFormalParameter;
     var functionParameter =
         defaultParameter.parameter as FunctionTypedFormalParameter;
     assertNoErrors();
     expect(functionParameter.returnType, isNull);
     expect(functionParameter.identifier, isNotNull);
     expect(functionParameter.typeParameters, isNull);
@@ skipping 218 matching lines @@
     assertNoErrors();
     expect(parameter, new isInstanceOf<FunctionTypedFormalParameter>());
     FunctionTypedFormalParameter functionParameter = parameter;
     expect(functionParameter.returnType, isNotNull);
     expect(functionParameter.identifier, isNotNull);
     expect(functionParameter.typeParameters, isNotNull);
     expect(functionParameter.parameters, isNotNull);
     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);
     assertNoErrors();
     expect(parameter, new isInstanceOf<SimpleFormalParameter>());
     SimpleFormalParameter simpleParameter = parameter;
     expect(simpleParameter.keyword, isNotNull);
     expect(simpleParameter.type, isNull);
     expect(simpleParameter.identifier, isNotNull);
   }
@@ skipping 5504 matching lines @@
 
   void test_import_as_show() {
     parseCompilationUnit("import 'dart:math' as M show E;");
   }
 
   void test_import_show_hide() {
     parseCompilationUnit(
         "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();
     expect(member, isNotNull);
     assertNoErrors();
     expect(member, new isInstanceOf<ClassDeclaration>());
     ClassDeclaration declaration = member;
     expect(declaration.documentationComment, isNull);
     expect(declaration.abstractKeyword, isNotNull);
     expect(declaration.extendsClause, isNull);
@@ skipping 203 matching lines @@
     expect(declaration.implementsClause, isNull);
     expect(declaration.classKeyword, isNotNull);
     expect(declaration.leftBracket, isNotNull);
     expect(declaration.name, isNotNull);
     expect(declaration.members, hasLength(0));
     expect(declaration.rightBracket, isNotNull);
     expect(declaration.typeParameters, isNotNull);
     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();
     expect(unit, isNotNull);
     assertNoErrors();
     expect(unit.scriptTag, isNull);
     expect(unit.directives, hasLength(0));
     expect(unit.declarations, hasLength(1));
   }
 
@@ skipping 450 matching lines @@
     createParser('typedef F();');
     CompilationUnitMember member = parseFullCompilationUnitMember();
     expect(member, isNotNull);
     assertNoErrors();
     expect(member, new isInstanceOf<FunctionTypeAlias>());
     FunctionTypeAlias typeAlias = member;
     expect(typeAlias.name.name, "F");
     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();
     expect(member, isNotNull);
     assertNoErrors();
     expect(member, new isInstanceOf<TopLevelVariableDeclaration>());
     TopLevelVariableDeclaration declaration = member;
     expect(declaration.semicolon, isNotNull);
     expect(declaration.variables, isNotNull);
     expect(declaration.variables.type, isNotNull);
     expect(declaration.variables.keyword, isNull);
   }
 
   void test_parseCompilationUnitMember_variable() {
     createParser('var x = 0;');
     CompilationUnitMember member = parseFullCompilationUnitMember();
     expect(member, isNotNull);
     assertNoErrors();
     expect(member, new isInstanceOf<TopLevelVariableDeclaration>());
     TopLevelVariableDeclaration declaration = member;
     expect(declaration.semicolon, isNotNull);
     expect(declaration.variables, isNotNull);
     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();
     expect(member, isNotNull);
     assertNoErrors();
     expect(member, new isInstanceOf<TopLevelVariableDeclaration>());
     TopLevelVariableDeclaration declaration = member;
     expect(declaration.semicolon, isNotNull);
     expect(declaration.variables, isNotNull);
   }
@@ skipping 15 matching lines @@
     expect(directive, isNotNull);
     assertNoErrors();
     expect(directive, new isInstanceOf<ExportDirective>());
     ExportDirective exportDirective = directive;
     expect(exportDirective.keyword, isNotNull);
     expect(exportDirective.uri, isNotNull);
     expect(exportDirective.combinators, hasLength(0));
     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();
     expect(directive, isNotNull);
     assertNoErrors();
     expect(directive, new isInstanceOf<ImportDirective>());
     ImportDirective importDirective = directive;
     expect(importDirective.keyword, isNotNull);
     expect(importDirective.uri, isNotNull);
     expect(importDirective.asKeyword, isNull);
@@ skipping 31 matching lines @@
 
   void test_parseDirective_library_3_components() {
     createParser("library a.b.c;");
     var lib = parseFullDirective() as LibraryDirective;
     expect(lib.name.components, hasLength(3));
     expect(lib.name.components[0].name, 'a');
     expect(lib.name.components[1].name, 'b');
     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();
     expect(directive, isNotNull);
     assertNoErrors();
     expect(directive, new isInstanceOf<PartDirective>());
     PartDirective partDirective = directive;
     expect(partDirective.partKeyword, isNotNull);
     expect(partDirective.uri, isNotNull);
     expect(partDirective.semicolon, isNotNull);
@@ skipping 16 matching lines @@
 
   void test_parseDirective_part_of_3_components() {
     createParser("part of a.b.c;");
     var partOf = parseFullDirective() as PartOfDirective;
     expect(partOf.libraryName.components, hasLength(3));
     expect(partOf.libraryName.components[0].name, 'a');
     expect(partOf.libraryName.components[1].name, 'b');
     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();
     expect(directive, isNotNull);
     assertNoErrors();
     expect(directive, new isInstanceOf<PartOfDirective>());
     PartOfDirective partOfDirective = directive;
     expect(partOfDirective.partKeyword, isNotNull);
     expect(partOfDirective.ofKeyword, isNotNull);
     expect(partOfDirective.libraryName, isNotNull);
@@ skipping 76 matching lines @@
     expect(declaration, isNotNull);
     assertNoErrors();
     expect(declaration.documentationComment, isNull);
     expect(declaration.enumKeyword, isNotNull);
     expect(declaration.leftBracket, isNotNull);
     expect(declaration.name, isNotNull);
     expect(declaration.constants, hasLength(2));
     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();
     expect(directive, isNotNull);
     assertNoErrors();
     expect(directive.keyword, isNotNull);
     expect(directive.uri, isNotNull);
     expect(directive.configurations, hasLength(2));
     expectDottedName(directive.configurations[0].name, ['a']);
     expectDottedName(directive.configurations[1].name, ['c']);
@@ skipping 614 matching lines @@
     expect(typeAlias.typedefKeyword, isNotNull);
     expect(typeAlias.name, isNotNull);
     expect(typeAlias.typeParameters, isNull);
     expect(typeAlias.semicolon, isNotNull);
     GenericFunctionType functionType = typeAlias.functionType;
     expect(functionType, isNotNull);
     expect(functionType.parameters, isNotNull);
     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');
+  }
 }