Issue 25385. Set documentation comment for enum constants.

pkg/analyzer/lib/src/dart/element/builder.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.src.dart.element.builder;
 
 import 'dart:collection';
 
 import 'package:analyzer/dart/ast/ast.dart';
 import 'package:analyzer/dart/ast/visitor.dart';
@@ skipping 158 matching lines @@
         ExportElementImpl exportElement = new ExportElementImpl(node.offset);
         exportElement.metadata = _getElementAnnotations(node.metadata);
         StringLiteral uriLiteral = node.uri;
         if (uriLiteral != null) {
           exportElement.uriOffset = uriLiteral.offset;
           exportElement.uriEnd = uriLiteral.end;
         }
         exportElement.uri = node.uriContent;
         exportElement.combinators = _buildCombinators(node);
         exportElement.exportedLibrary = exportedLibrary;
-        _setDoc(exportElement, node);
+        setElementDocumentationComment(exportElement, node);
         node.element = exportElement;
         exports.add(exportElement);
         if (exportSourceKindMap[exportedSource] != SourceKind.LIBRARY) {
           errors.add(new AnalysisError(
               exportedSource,
               uriLiteral.offset,
               uriLiteral.length,
               CompileTimeErrorCode.EXPORT_OF_NON_LIBRARY,
               [uriLiteral.toSource()]));
         }
@@ skipping 21 matching lines @@
         importElement.metadata = _getElementAnnotations(node.metadata);
         StringLiteral uriLiteral = node.uri;
         if (uriLiteral != null) {
           importElement.uriOffset = uriLiteral.offset;
           importElement.uriEnd = uriLiteral.end;
         }
         importElement.uri = uriContent;
         importElement.deferred = node.deferredKeyword != null;
         importElement.combinators = _buildCombinators(node);
         importElement.importedLibrary = importedLibrary;
-        _setDoc(importElement, node);
+        setElementDocumentationComment(importElement, node);
         SimpleIdentifier prefixNode = node.prefix;
         if (prefixNode != null) {
           importElement.prefixOffset = prefixNode.offset;
           String prefixName = prefixNode.name;
           PrefixElementImpl prefix = nameToPrefixMap[prefixName];
           if (prefix == null) {
             prefix = new PrefixElementImpl.forNode(prefixNode);
             nameToPrefixMap[prefixName] = prefix;
           }
           importElement.prefix = prefix;
@@ skipping 33 matching lines @@
    */
   List<ElementAnnotation> _getElementAnnotations(
       NodeList<Annotation> metadata) {
     if (metadata.isEmpty) {
       return ElementAnnotation.EMPTY_LIST;
     }
     return metadata.map((Annotation a) => a.elementAnnotation).toList();
   }
 
   /**
-   * If the given [node] has a documentation comment, remember its content
-   * and range into the given [element].
-   */
-  void _setDoc(ElementImpl element, AnnotatedNode node) {
-    Comment comment = node.documentationComment;
-    if (comment != null && comment.isDocumentation) {
-      element.documentationComment =
-          comment.tokens.map((Token t) => t.lexeme).join('\n');
-      element.setDocRange(comment.offset, comment.length);
-    }
-  }
-
-  /**
    * Build the element model representing the combinators declared by
    * the given [directive].
    */
   static List<NamespaceCombinator> _buildCombinators(
       NamespaceDirective directive) {
     _NamespaceCombinatorBuilder namespaceCombinatorBuilder =
         new _NamespaceCombinatorBuilder();
     for (Combinator combinator in directive.combinators) {
       combinator.accept(namespaceCombinatorBuilder);
     }
@@ skipping 110 matching lines @@
     }
     SimpleIdentifier className = node.name;
     ClassElementImpl element = new ClassElementImpl.forNode(className);
     element.metadata = _createElementAnnotations(node.metadata);
     List<TypeParameterElement> typeParameters = holder.typeParameters;
     List<DartType> typeArguments = _createTypeParameterTypes(typeParameters);
     InterfaceTypeImpl interfaceType = new InterfaceTypeImpl(element);
     interfaceType.typeArguments = typeArguments;
     element.type = interfaceType;
     element.typeParameters = typeParameters;
-    _setDoc(element, node);
+    setElementDocumentationComment(element, node);
     element.abstract = node.isAbstract;
     element.accessors = holder.accessors;
     List<ConstructorElement> constructors = holder.constructors;
     if (constructors.isEmpty) {
       constructors = _createDefaultConstructors(element);
     }
     element.constructors = constructors;
     element.fields = holder.fields;
     element.methods = holder.methods;
     // Function types must be initialized after the enclosing element has been
@@ skipping 30 matching lines @@
     ClassElementImpl element = new ClassElementImpl.forNode(className);
     element.metadata = _createElementAnnotations(node.metadata);
     element.abstract = node.abstractKeyword != null;
     element.mixinApplication = true;
     List<TypeParameterElement> typeParameters = holder.typeParameters;
     element.typeParameters = typeParameters;
     List<DartType> typeArguments = _createTypeParameterTypes(typeParameters);
     InterfaceTypeImpl interfaceType = new InterfaceTypeImpl(element);
     interfaceType.typeArguments = typeArguments;
     element.type = interfaceType;
-    _setDoc(element, node);
+    setElementDocumentationComment(element, node);
     _currentHolder.addType(element);
     className.staticElement = element;
     holder.validate();
     return null;
   }
 
   @override
   Object visitConstructorDeclaration(ConstructorDeclaration node) {
     ElementHolder holder = new ElementHolder();
     bool wasInFunction = _inFunction;
     _inFunction = true;
     try {
       _visitChildren(holder, node);
     } finally {
       _inFunction = wasInFunction;
     }
     FunctionBody body = node.body;
     SimpleIdentifier constructorName = node.name;
     ConstructorElementImpl element =
         new ConstructorElementImpl.forNode(constructorName);
     element.metadata = _createElementAnnotations(node.metadata);
-    _setDoc(element, node);
+    setElementDocumentationComment(element, node);
     if (node.externalKeyword != null) {
       element.external = true;
     }
     if (node.factoryKeyword != null) {
       element.factory = true;
     }
     element.functions = holder.functions;
     element.labels = holder.labels;
     element.localVariables = holder.localVariables;
     element.parameters = holder.parameters;
@@ skipping 87 matching lines @@
     holder.validate();
     return null;
   }
 
   @override
   Object visitEnumDeclaration(EnumDeclaration node) {
     SimpleIdentifier enumName = node.name;
     ClassElementImpl enumElement = new ClassElementImpl.forNode(enumName);
     enumElement.metadata = _createElementAnnotations(node.metadata);
     enumElement.enum2 = true;
-    _setDoc(enumElement, node);
+    setElementDocumentationComment(enumElement, node);
     InterfaceTypeImpl enumType = new InterfaceTypeImpl(enumElement);
     enumElement.type = enumType;
     // The equivalent code for enums in the spec shows a single constructor,
     // but that constructor is not callable (since it is a compile-time error
     // to subclass, mix-in, implement, or explicitly instantiate an enum).  So
     // we represent this as having no constructors.
     enumElement.constructors = ConstructorElement.EMPTY_LIST;
     _currentHolder.addEnum(enumElement);
     enumName.staticElement = enumElement;
     return super.visitEnumDeclaration(node);
@@ skipping 60 matching lines @@
       } finally {
         _inFunction = wasInFunction;
       }
       FunctionBody body = expression.body;
       Token property = node.propertyKeyword;
       if (property == null || _inFunction) {
         SimpleIdentifier functionName = node.name;
         FunctionElementImpl element =
             new FunctionElementImpl.forNode(functionName);
         element.metadata = _createElementAnnotations(node.metadata);
-        _setDoc(element, node);
+        setElementDocumentationComment(element, node);
         if (node.externalKeyword != null) {
           element.external = true;
         }
         element.functions = holder.functions;
         element.labels = holder.labels;
         element.localVariables = holder.localVariables;
         element.parameters = holder.parameters;
         element.typeParameters = holder.typeParameters;
         if (body.isAsynchronous) {
           element.asynchronous = true;
@@ skipping 25 matching lines @@
         if (variable == null) {
           variable = new TopLevelVariableElementImpl(node.name.name, -1);
           variable.final2 = true;
           variable.synthetic = true;
           _currentHolder.addTopLevelVariable(variable);
         }
         if (node.isGetter) {
           PropertyAccessorElementImpl getter =
               new PropertyAccessorElementImpl.forNode(propertyNameNode);
           getter.metadata = _createElementAnnotations(node.metadata);
-          _setDoc(getter, node);
+          setElementDocumentationComment(getter, node);
           if (node.externalKeyword != null) {
             getter.external = true;
           }
           getter.functions = holder.functions;
           getter.labels = holder.labels;
           getter.localVariables = holder.localVariables;
           if (body.isAsynchronous) {
             getter.asynchronous = true;
           }
           if (body.isGenerator) {
             getter.generator = true;
           }
           getter.variable = variable;
           getter.getter = true;
           getter.static = true;
           variable.getter = getter;
           if (node.returnType == null) {
             getter.hasImplicitReturnType = true;
           }
           _currentHolder.addAccessor(getter);
           expression.element = getter;
           propertyNameNode.staticElement = getter;
         } else {
           PropertyAccessorElementImpl setter =
               new PropertyAccessorElementImpl.forNode(propertyNameNode);
           setter.metadata = _createElementAnnotations(node.metadata);
-          _setDoc(setter, node);
+          setElementDocumentationComment(setter, node);
           if (node.externalKeyword != null) {
             setter.external = true;
           }
           setter.functions = holder.functions;
           setter.labels = holder.labels;
           setter.localVariables = holder.localVariables;
           setter.parameters = holder.parameters;
           if (body.isAsynchronous) {
             setter.asynchronous = true;
           }
@@ skipping 68 matching lines @@
   @override
   Object visitFunctionTypeAlias(FunctionTypeAlias node) {
     ElementHolder holder = new ElementHolder();
     _visitChildren(holder, node);
     SimpleIdentifier aliasName = node.name;
     List<ParameterElement> parameters = holder.parameters;
     List<TypeParameterElement> typeParameters = holder.typeParameters;
     FunctionTypeAliasElementImpl element =
         new FunctionTypeAliasElementImpl.forNode(aliasName);
     element.metadata = _createElementAnnotations(node.metadata);
-    _setDoc(element, node);
+    setElementDocumentationComment(element, node);
     element.parameters = parameters;
     element.typeParameters = typeParameters;
     _createTypeParameterTypes(typeParameters);
     element.type = new FunctionTypeImpl.forTypedef(element);
     _currentHolder.addTypeAlias(element);
     aliasName.staticElement = element;
     holder.validate();
     return null;
   }
 
@@ skipping 64 matching lines @@
       if (property == null) {
         SimpleIdentifier methodName = node.name;
         String nameOfMethod = methodName.name;
         if (nameOfMethod == TokenType.MINUS.lexeme &&
             node.parameters.parameters.length == 0) {
           nameOfMethod = "unary-";
         }
         MethodElementImpl element =
             new MethodElementImpl(nameOfMethod, methodName.offset);
         element.metadata = _createElementAnnotations(node.metadata);
-        _setDoc(element, node);
+        setElementDocumentationComment(element, node);
         element.abstract = node.isAbstract;
         if (node.externalKeyword != null) {
           element.external = true;
         }
         element.functions = holder.functions;
         element.labels = holder.labels;
         element.localVariables = holder.localVariables;
         element.parameters = holder.parameters;
         element.static = isStatic;
         element.typeParameters = holder.typeParameters;
@@ skipping 17 matching lines @@
           field = new FieldElementImpl(node.name.name, -1);
           field.final2 = true;
           field.static = isStatic;
           field.synthetic = true;
           _currentHolder.addField(field);
         }
         if (node.isGetter) {
           PropertyAccessorElementImpl getter =
               new PropertyAccessorElementImpl.forNode(propertyNameNode);
           getter.metadata = _createElementAnnotations(node.metadata);
-          _setDoc(getter, node);
+          setElementDocumentationComment(getter, node);
           if (node.externalKeyword != null) {
             getter.external = true;
           }
           getter.functions = holder.functions;
           getter.labels = holder.labels;
           getter.localVariables = holder.localVariables;
           if (body.isAsynchronous) {
             getter.asynchronous = true;
           }
           if (body.isGenerator) {
             getter.generator = true;
           }
           getter.variable = field;
           getter.abstract = node.isAbstract;
           getter.getter = true;
           getter.static = isStatic;
           field.getter = getter;
           if (node.returnType == null) {
             getter.hasImplicitReturnType = true;
           }
           _currentHolder.addAccessor(getter);
           propertyNameNode.staticElement = getter;
         } else {
           PropertyAccessorElementImpl setter =
               new PropertyAccessorElementImpl.forNode(propertyNameNode);
           setter.metadata = _createElementAnnotations(node.metadata);
-          _setDoc(setter, node);
+          setElementDocumentationComment(setter, node);
           if (node.externalKeyword != null) {
             setter.external = true;
           }
           setter.functions = holder.functions;
           setter.labels = holder.labels;
           setter.localVariables = holder.localVariables;
           setter.parameters = holder.parameters;
           if (body.isAsynchronous) {
             setter.asynchronous = true;
           }
@@ skipping 124 matching lines @@
     if (_inFieldContext) {
       SimpleIdentifier fieldName = node.name;
       FieldElementImpl field;
       if ((isConst || isFinal) && hasInitializer) {
         field = new ConstFieldElementImpl.forNode(fieldName);
       } else {
         field = new FieldElementImpl.forNode(fieldName);
       }
       element = field;
       if (node.parent.parent is FieldDeclaration) {
-        _setDoc(element, node.parent.parent);
+        setElementDocumentationComment(element, node.parent.parent);
       }
       if ((node.parent as VariableDeclarationList).type == null) {
         field.hasImplicitType = true;
       }
       _currentHolder.addField(field);
       fieldName.staticElement = field;
     } else if (_inFunction) {
       SimpleIdentifier variableName = node.name;
       LocalVariableElementImpl variable;
       if (isConst && hasInitializer) {
@@ skipping 14 matching lines @@
     } else {
       SimpleIdentifier variableName = node.name;
       TopLevelVariableElementImpl variable;
       if (isConst && hasInitializer) {
         variable = new ConstTopLevelVariableElementImpl.forNode(variableName);
       } else {
         variable = new TopLevelVariableElementImpl.forNode(variableName);
       }
       element = variable;
       if (node.parent.parent is TopLevelVariableDeclaration) {
-        _setDoc(element, node.parent.parent);
+        setElementDocumentationComment(element, node.parent.parent);
       }
       if ((node.parent as VariableDeclarationList).type == null) {
         variable.hasImplicitType = true;
       }
       _currentHolder.addTopLevelVariable(variable);
       variableName.staticElement = element;
     }
     element.const3 = isConst;
     element.final2 = isFinal;
     if (hasInitializer) {
@@ skipping 150 matching lines @@
         return parent.body;
       } else if (parent is MethodDeclaration) {
         return parent.body;
       }
       parent = parent.parent;
     }
     return null;
   }
 
   /**
-   * If the given [node] has a documentation comment, remember its content
-   * and range into the given [element].
-   */
-  void _setDoc(ElementImpl element, AnnotatedNode node) {
-    Comment comment = node.documentationComment;
-    if (comment != null && comment.isDocumentation) {
-      element.documentationComment =
-          comment.tokens.map((Token t) => t.lexeme).join('\n');
-      element.setDocRange(comment.offset, comment.length);
-    }
-  }
-
-  /**
    * Sets the visible source range for formal parameter.
    */
   void _setParameterVisibleRange(
       FormalParameter node, ParameterElementImpl element) {
     FunctionBody body = _getFunctionBody(node);
     if (body != null) {
       element.setVisibleRange(body.offset, body.length);
     }
   }
 
@@ skipping 85 matching lines @@
     return null;
   }
 
   /**
    * Return the lexical identifiers associated with the given [identifiers].
    */
   static List<String> _getIdentifiers(NodeList<SimpleIdentifier> identifiers) {
     return identifiers.map((identifier) => identifier.name).toList();
   }
 }