Add support for documentation comments to most of AstBuilder.

pkg/front_end/lib/src/fasta/analyzer/ast_builder.dart

 // Copyright (c) 2016, 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 fasta.analyzer.ast_builder;
 
 import 'package:analyzer/analyzer.dart';
 import 'package:analyzer/dart/ast/ast_factory.dart' show AstFactory;
 import 'package:analyzer/dart/ast/standard_ast_factory.dart' as standard;
 import 'package:analyzer/dart/ast/token.dart' as analyzer show Token;
 import 'package:analyzer/dart/element/element.dart' show Element;
 import '../parser/parser.dart' show FormalParameterType;
 import '../scanner/token.dart' show BeginGroupToken, Token;
 
 import '../errors.dart' show internalError;
 import '../kernel/kernel_builder.dart'
     show Builder, KernelLibraryBuilder, ProcedureBuilder;
 import '../parser/identifier_context.dart' show IdentifierContext;
 import '../quote.dart';
 import '../source/scope_listener.dart'
     show JumpTargetKind, NullValue, Scope, ScopeListener;
 import 'analyzer.dart' show toKernel;
 import 'element_store.dart'
     show
         AnalyzerLocalVariableElemment,
         AnalyzerParameterElement,
         ElementStore,
         KernelClassElement;
-import 'token_utils.dart' show toAnalyzerToken;
+import 'token_utils.dart' show toAnalyzerToken, toAnalyzerCommentToken;
 
 class AstBuilder extends ScopeListener {
   final AstFactory ast = standard.astFactory;
 
   final KernelLibraryBuilder library;
 
   final Builder member;
 
   final ElementStore elementStore;
 
@@ skipping 135 matching lines @@
     if (context.inLibraryOrPartOfDeclaration) {
       if (!context.isContinuation) {
         push([identifier]);
       } else {
         push(identifier);
       }
     } else if (context == IdentifierContext.enumValueDeclaration) {
       // TODO(paulberry): analyzer's ASTs allow for enumerated values to have
       // metadata, but the spec doesn't permit it.
       List<Annotation> metadata;
-      // TODO(paulberry): capture doc comments.  See dartbug.com/28851.
-      Comment comment = null;
+      Comment comment = _toAnalyzerComment(token.precedingComments);
       push(ast.enumConstantDeclaration(comment, metadata, identifier));
     } else {
       if (context.isScopeReference) {
         String name = token.value;
         Builder builder = scope.lookup(name, token.charOffset, uri);
         if (builder != null) {
           Element element = elementStore[builder];
           assert(element != null);
           identifier.staticElement = element;
         }
@@ skipping 426 matching lines @@
     SimpleIdentifier name;
     if (nameOrFunctionTypedParameter is FormalParameter) {
       node = nameOrFunctionTypedParameter;
       name = nameOrFunctionTypedParameter.identifier;
     } else {
       name = nameOrFunctionTypedParameter;
       TypeAnnotation type = pop();
       _Modifiers modifiers = pop();
       Token keyword = modifiers?.finalConstOrVarKeyword;
       pop(); // TODO(paulberry): Metadata.
+      Comment comment = pop();
       if (thisKeyword == null) {
         node = ast.simpleFormalParameter2(
+            comment: comment,
             covariantKeyword: toAnalyzerToken(covariantKeyword),
             keyword: toAnalyzerToken(keyword),
             type: type,
             identifier: name);
       } else {
         // TODO(scheglov): Ideally the period token should be passed in.
         Token period = identical('.', thisKeyword.next?.stringValue)
             ? thisKeyword.next
             : null;
         node = ast.fieldFormalParameter2(
+            comment: comment,
             covariantKeyword: toAnalyzerToken(covariantKeyword),
             keyword: toAnalyzerToken(keyword),
             type: type,
             thisKeyword: toAnalyzerToken(thisKeyword),
             period: toAnalyzerToken(period),
             identifier: name);
       }
     }
 
     ParameterKind analyzerKind = _toAnalyzerParameterKind(kind);
@@ skipping 21 matching lines @@
 
     {
       _Modifiers modifiers = pop();
       if (modifiers != null) {
         // TODO(scheglov): Report error.
         internalError('Unexpected modifier. Report an error.');
       }
     }
 
     pop(); // TODO(paulberry): Metadata.
+    Comment comment = pop();
 
     FormalParameter node;
     if (thisKeyword == null) {
       node = ast.functionTypedFormalParameter2(
+          comment: comment,
           covariantKeyword: toAnalyzerToken(covariantKeyword),
           returnType: returnType,
           identifier: name,
           typeParameters: typeParameters,
           parameters: formalParameters);
     } else {
       // TODO(scheglov): Ideally the period token should be passed in.
       Token period = identical('.', thisKeyword?.next?.stringValue)
           ? thisKeyword.next
           : null;
       node = ast.fieldFormalParameter2(
+          comment: comment,
           covariantKeyword: toAnalyzerToken(covariantKeyword),
           type: returnType,
           thisKeyword: toAnalyzerToken(thisKeyword),
           period: toAnalyzerToken(period),
           identifier: name,
           typeParameters: typeParameters,
           parameters: formalParameters);
     }
 
     scope[name.name] = name.staticElement = new AnalyzerParameterElement(node);
@@ skipping 127 matching lines @@
     debugEvent("TopLevelMethod");
     FunctionBody body = pop();
     FormalParameterList parameters = pop();
     TypeParameterList typeParameters = pop();
     SimpleIdentifier name = pop();
     analyzer.Token propertyKeyword = toAnalyzerToken(getOrSet);
     TypeAnnotation returnType = pop();
     _Modifiers modifiers = pop();
     Token externalKeyword = modifiers?.externalKeyword;
     List<Annotation> metadata = pop();
-    // TODO(paulberry): capture doc comments.  See dartbug.com/28851.
-    Comment comment = null;
+    Comment comment = pop();
     push(ast.functionDeclaration(
         comment,
         metadata,
         toAnalyzerToken(externalKeyword),
         returnType,
         propertyKeyword,
         name,
         ast.functionExpression(typeParameters, parameters, body)));
   }
 
@@ skipping 31 matching lines @@
 
   void endImport(Token importKeyword, Token deferredKeyword, Token asKeyword,
       Token semicolon) {
     debugEvent("Import");
     List<Combinator> combinators = pop();
     SimpleIdentifier prefix;
     if (asKeyword != null) prefix = pop();
     List<Configuration> configurations = pop();
     StringLiteral uri = pop();
     List<Annotation> metadata = pop();
-    assert(metadata == null);
-    // TODO(paulberry): capture doc comments.  See dartbug.com/28851.
-    Comment comment = null;
+    assert(metadata == null); // TODO(paulberry): fix.
+    Comment comment = pop();
     push(ast.importDirective(
         comment,
         metadata,
         toAnalyzerToken(importKeyword),
         uri,
         configurations,
         toAnalyzerToken(deferredKeyword),
         toAnalyzerToken(asKeyword),
         prefix,
         combinators,
         toAnalyzerToken(semicolon)));
   }
 
   void endExport(Token exportKeyword, Token semicolon) {
     debugEvent("Export");
     List<Combinator> combinators = pop();
     List<Configuration> configurations = pop();
     StringLiteral uri = pop();
     List<Annotation> metadata = pop();
     assert(metadata == null);
-    // TODO(paulberry): capture doc comments.  See dartbug.com/28851.
-    Comment comment = null;
+    Comment comment = pop();
     push(ast.exportDirective(comment, metadata, toAnalyzerToken(exportKeyword),
         uri, configurations, combinators, toAnalyzerToken(semicolon)));
   }
 
   @override
   void endDottedName(int count, Token firstIdentifier) {
     debugEvent("DottedName");
     List<SimpleIdentifier> components = popList(count);
     push(ast.dottedName(components));
   }
@@ skipping 95 matching lines @@
     } else {
       internalError('Unexpected kind of supertype ${supertype.runtimeType}');
     }
     TypeParameterList typeParameters = pop();
     SimpleIdentifier name = pop();
     assert(className == name.name);
     className = null;
     _Modifiers modifiers = pop();
     Token abstractKeyword = modifiers?.abstractKeyword;
     List<Annotation> metadata = pop();
-    // TODO(paulberry): capture doc comments.  See dartbug.com/28851.
-    Comment comment = null;
+    Comment comment = pop();
     push(ast.classDeclaration(
         comment,
         metadata,
         toAnalyzerToken(abstractKeyword),
         toAnalyzerToken(classKeyword),
         name,
         typeParameters,
         extendsClause,
         withClause,
         implementsClause,
@@ skipping 24 matching lines @@
     var superclass = mixinApplication.supertype;
     var withClause = ast.withClause(
         toAnalyzerToken(mixinApplication.withKeyword),
         mixinApplication.mixinTypes);
     analyzer.Token equals = toAnalyzerToken(equalsToken);
     TypeParameterList typeParameters = pop();
     SimpleIdentifier name = pop();
     _Modifiers modifiers = pop();
     Token abstractKeyword = modifiers?.abstractKeyword;
     List<Annotation> metadata = pop();
-    // TODO(paulberry): capture doc comments.  See dartbug.com/28851.
-    Comment comment = null;
+    Comment comment = pop();
     push(ast.classTypeAlias(
         comment,
         metadata,
         toAnalyzerToken(classKeyword),
         name,
         typeParameters,
         equals,
         toAnalyzerToken(abstractKeyword),
         superclass,
         withClause,
         implementsClause,
         toAnalyzerToken(endToken)));
   }
 
   @override
   void endLibraryName(Token libraryKeyword, Token semicolon) {
     debugEvent("LibraryName");
     List<SimpleIdentifier> libraryName = pop();
     var name = ast.libraryIdentifier(libraryName);
     List<Annotation> metadata = pop();
-    // TODO(paulberry): capture doc comments.  See dartbug.com/28851.
-    Comment comment = null;
+    Comment comment = pop();
     push(ast.libraryDirective(comment, metadata,
         toAnalyzerToken(libraryKeyword), name, toAnalyzerToken(semicolon)));
   }
 
   @override
   void handleQualified(Token period) {
     SimpleIdentifier identifier = pop();
     var prefix = pop();
     if (prefix is List) {
       // We're just accumulating components into a list.
       prefix.add(identifier);
       push(prefix);
     } else if (prefix is SimpleIdentifier) {
       // TODO(paulberry): resolve [identifier].  Note that BodyBuilder handles
       // this situation using SendAccessor.
       push(ast.prefixedIdentifier(prefix, toAnalyzerToken(period), identifier));
     } else {
       // TODO(paulberry): implement.
       logEvent('Qualified with >1 dot');
     }
   }
 
   @override
   void endPart(Token partKeyword, Token semicolon) {
     debugEvent("Part");
     StringLiteral uri = pop();
     List<Annotation> metadata = pop();
-    // TODO(paulberry): capture doc comments.  See dartbug.com/28851.
-    Comment comment = null;
+    Comment comment = pop();
     push(ast.partDirective(comment, metadata, toAnalyzerToken(partKeyword), uri,
         toAnalyzerToken(semicolon)));
   }
 
   @override
   void endPartOf(Token partKeyword, Token semicolon) {
     debugEvent("PartOf");
     List<SimpleIdentifier> libraryName = pop();
     var name = ast.libraryIdentifier(libraryName);
     StringLiteral uri = null; // TODO(paulberry)
     // TODO(paulberry,ahe): seems hacky.  It would be nice if the parser passed
     // in a reference to the "of" keyword.
     var ofKeyword = partKeyword.next;
     List<Annotation> metadata = pop();
-    // TODO(paulberry): capture doc comments.  See dartbug.com/28851.
-    Comment comment = null;
+    Comment comment = pop();
     push(ast.partOfDirective(comment, metadata, toAnalyzerToken(partKeyword),
         toAnalyzerToken(ofKeyword), uri, name, toAnalyzerToken(semicolon)));
   }
 
   void endUnnamedFunction(Token token) {
     // TODO(paulberry): set up scopes properly to resolve parameters and type
     // variables.  Note that this is tricky due to the handling of initializers
     // in constructors, so the logic should be shared with BodyBuilder as much
     // as possible.
     debugEvent("UnnamedFunction");
@@ skipping 20 matching lines @@
 
   void endTopLevelFields(int count, Token beginToken, Token endToken) {
     debugEvent("TopLevelFields");
     List<VariableDeclaration> variables = popList(count);
     TypeAnnotation type = pop();
     _Modifiers modifiers = pop();
     Token keyword = modifiers?.finalConstOrVarKeyword;
     var variableList = ast.variableDeclarationList(
         null, null, toAnalyzerToken(keyword), type, variables);
     List<Annotation> metadata = pop();
-    // TODO(paulberry): capture doc comments.  See dartbug.com/28851.
-    Comment comment = null;
+    Comment comment = pop();
     push(ast.topLevelVariableDeclaration(
         comment, metadata, variableList, toAnalyzerToken(endToken)));
   }
 
   @override
   void endTypeVariable(Token token, Token extendsOrSuper) {
     // TODO(paulberry): set up scopes properly to resolve parameters and type
     // variables.  Note that this is tricky due to the handling of initializers
     // in constructors, so the logic should be shared with BodyBuilder as much
     // as possible.
@@ skipping 21 matching lines @@
     FunctionBody body = pop();
     ConstructorName redirectedConstructor = null; // TODO(paulberry)
     List<ConstructorInitializer> initializers = null; // TODO(paulberry)
     Token separator = null; // TODO(paulberry)
     FormalParameterList parameters = pop();
     TypeParameterList typeParameters = pop(); // TODO(paulberry)
     var name = pop();
     TypeAnnotation returnType = pop(); // TODO(paulberry)
     _Modifiers modifiers = pop();
     List<Annotation> metadata = pop();
-    // TODO(paulberry): capture doc comments.  See dartbug.com/28851.
-    Comment comment = null;
+    Comment comment = pop();
     Token period;
     void unnamedConstructor(
         SimpleIdentifier returnType, SimpleIdentifier name) {
       push(ast.constructorDeclaration(
           comment,
           metadata,
           toAnalyzerToken(modifiers?.externalKeyword),
           toAnalyzerToken(modifiers?.finalConstOrVarKeyword),
           null, // TODO(paulberry): factoryKeyword
           returnType,
@@ skipping 53 matching lines @@
   @override
   void endFunctionTypeAlias(
       Token typedefKeyword, Token equals, Token endToken) {
     debugEvent("FunctionTypeAlias");
     if (equals == null) {
       FormalParameterList parameters = pop();
       TypeParameterList typeParameters = pop();
       SimpleIdentifier name = pop();
       TypeAnnotation returnType = pop();
       List<Annotation> metadata = pop();
-      // TODO(paulberry): capture doc comments.  See dartbug.com/28851.
-      Comment comment = null;
+      Comment comment = pop();
       push(ast.functionTypeAlias(
           comment,
           metadata,
           toAnalyzerToken(typedefKeyword),
           returnType,
           name,
           typeParameters,
           parameters,
           toAnalyzerToken(endToken)));
     } else {
       TypeAnnotation type = pop();
       TypeParameterList templateParameters = pop();
       SimpleIdentifier name = pop();
       List<Annotation> metadata = pop();
-      // TODO(paulberry): capture doc comments.  See dartbug.com/28851.
-      Comment comment = null;
+      Comment comment = pop();
       if (type is! GenericFunctionType) {
         // TODO(paulberry) Generate an error and recover (better than
         // this).
         type = null;
       }
       push(ast.genericTypeAlias(
           comment,
           metadata,
           toAnalyzerToken(typedefKeyword),
           name,
           templateParameters,
           toAnalyzerToken(equals),
           type,
           toAnalyzerToken(endToken)));
     }
   }
 
   @override
   void endEnum(Token enumKeyword, Token endBrace, int count) {
     debugEvent("Enum");
     List<EnumConstantDeclaration> constants = popList(count);
     // TODO(paulberry,ahe): the parser should pass in the openBrace token.
     var openBrace = enumKeyword.next.next as BeginGroupToken;
     // TODO(paulberry): what if the '}' is missing and the parser has performed
     // error recovery?
     Token closeBrace = openBrace.endGroup;
     SimpleIdentifier name = pop();
     List<Annotation> metadata = pop();
-    // TODO(paulberry): capture doc comments.  See dartbug.com/28851.
-    Comment comment = null;
+    Comment comment = pop();
     push(ast.enumDeclaration(
         comment,
         metadata,
         toAnalyzerToken(enumKeyword),
         name,
         toAnalyzerToken(openBrace),
         constants,
         toAnalyzerToken(closeBrace)));
   }
 
   @override
   void endTypeArguments(int count, Token beginToken, Token endToken) {
     debugEvent("TypeArguments");
     List<TypeAnnotation> arguments = popList(count);
     push(ast.typeArgumentList(
         toAnalyzerToken(beginToken), arguments, toAnalyzerToken(endToken)));
   }
 
   @override
   void endFields(
       int count, Token covariantKeyword, Token beginToken, Token endToken) {
     debugEvent("Fields");
     List<VariableDeclaration> variables = popList(count);
     TypeAnnotation type = pop();
     _Modifiers modifiers = pop();
     var variableList = ast.variableDeclarationList(null, null,
         toAnalyzerToken(modifiers?.finalConstOrVarKeyword), type, variables);
     List<Annotation> metadata = pop();
-    // TODO(paulberry): capture doc comments.  See dartbug.com/28851.
-    Comment comment = null;
+    Comment comment = pop();
     push(ast.fieldDeclaration2(
         comment: comment,
         metadata: metadata,
         covariantKeyword: toAnalyzerToken(covariantKeyword),
         staticKeyword: toAnalyzerToken(modifiers?.staticKeyword),
         fieldList: variableList,
         semicolon: toAnalyzerToken(endToken)));
   }
 
   @override
   void handleOperatorName(Token operatorKeyword, Token token) {
     debugEvent("OperatorName");
     push(new _OperatorName(operatorKeyword,
         ast.simpleIdentifier(toAnalyzerToken(token), isDeclaration: true)));
   }
 
+  @override
+  void beginMetadataStar(Token token) {
+    debugEvent("beginMetadataStar");
+    if (token.precedingComments != null) {
+      push(_toAnalyzerComment(token.precedingComments));
+    } else {
+      push(NullValue.Comments);
+    }
+  }
+
   ParameterKind _toAnalyzerParameterKind(FormalParameterType type) {
     if (type == FormalParameterType.POSITIONAL) {
       return ParameterKind.POSITIONAL;
     } else if (type == FormalParameterType.NAMED) {
       return ParameterKind.NAMED;
     } else {
       return ParameterKind.REQUIRED;
     }
   }
+
+  Comment _toAnalyzerComment(Token comments) {
+    if (comments == null) return null;
+
+    // This is temporary placeholder code to get tests to pass.
+    // TODO(paulberry): after analyzer and fasta token representations are
+    // unified, refactor the code in analyzer's parser that handles
+    // documentation comments so that it is reusable, and reuse it here.
+    // See Parser.parseCommentAndMetadata
+    var tokens = <analyzer.Token>[toAnalyzerCommentToken(comments)];
+    var references = <CommentReference>[];
+    return ast.documentationComment(tokens, references);
+  }
 }
 
 /// Data structure placed on the stack to represent a class body.
 ///
 /// This is needed because analyzer has no separate AST representation of a
 /// class body; it simply stores all of the relevant data in the
 /// [ClassDeclaration] object.
 class _ClassBody {
   final Token beginToken;
 
@@ skipping 73 matching lines @@
       } else if (identical('static', s)) {
         staticKeyword = token;
       } else if (identical('var', s)) {
         finalConstOrVarKeyword = token;
       } else {
         internalError('Unhandled modifier: $s');
       }
     }
   }
 }