Issue 8742. Preserve leading line comments during java2dart translation.

pkg/analyzer/lib/src/generated/ast.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.ast;
 
 import 'dart:collection';
@@ skipping 1022 matching lines @@
    * Otherwise, return `null`.
    *
    * This method is only intended to be used by [Expression#getPropagatedParameterElement].
    *
    * @param expression the expression corresponding to the parameter to be returned
    * @return the parameter element representing the parameter to which the value of the expression
    *         will be bound
    */
   ParameterElement getPropagatedParameterElementFor(Expression expression) {
     if (_correspondingPropagatedParameters == null) {
+      // Either the AST structure has not been resolved or the invocation of which this list is a
+      // part could not be resolved.
       return null;
     }
     int index = _arguments.indexOf(expression);
     if (index < 0) {
+      // The expression isn't a child of this node.
       return null;
     }
     return _correspondingPropagatedParameters[index];
   }
 
   /**
    * If the given expression is a child of this list, and the AST structure has been resolved, and
    * the function being invoked is known based on static type information, and the expression
    * corresponds to one of the parameters of the function being invoked, then return the parameter
    * element representing the parameter to which the value of the given expression will be bound.
    * Otherwise, return `null`.
    *
    * This method is only intended to be used by [Expression#getStaticParameterElement].
    *
    * @param expression the expression corresponding to the parameter to be returned
    * @return the parameter element representing the parameter to which the value of the expression
    *         will be bound
    */
   ParameterElement getStaticParameterElementFor(Expression expression) {
     if (_correspondingStaticParameters == null) {
+      // Either the AST structure has not been resolved or the invocation of which this list is a
+      // part could not be resolved.
       return null;
     }
     int index = _arguments.indexOf(expression);
     if (index < 0) {
+      // The expression isn't a child of this node.
       return null;
     }
     return _correspondingStaticParameters[index];
   }
 }
 
 /**
  * Instances of the class `AsExpression` represent an 'as' expression.
  *
  * <pre>
@@ skipping 4566 matching lines @@
   }
 
   accept(ASTVisitor visitor) => visitor.visitFunctionExpression(this);
 
   Token get beginToken {
     if (_parameters != null) {
       return _parameters.beginToken;
     } else if (_body != null) {
       return _body.beginToken;
     }
+    // This should never be reached because external functions must be named, hence either the body
+    // or the name should be non-null.
     throw new IllegalStateException("Non-external functions must have a body");
   }
 
   /**
    * Return the body of the function, or `null` if this is an external function.
    *
    * @return the body of the function
    */
   FunctionBody get body => _body;
 
   Token get endToken {
     if (_body != null) {
       return _body.endToken;
     } else if (_parameters != null) {
       return _parameters.endToken;
     }
+    // This should never be reached because external functions must be named, hence either the body
+    // or the name should be non-null.
     throw new IllegalStateException("Non-external functions must have a body");
   }
 
   /**
    * Return the parameters associated with the function.
    *
    * @return the parameters associated with the function
    */
   FormalParameterList get parameters => _parameters;
 
@@ skipping 676 matching lines @@
  *
  * <pre>
  * importDirective ::=
  *     [Annotation] 'import' [StringLiteral] ('as' identifier)? [Combinator]* ';'
  * </pre>
  *
  * @coverage dart.engine.ast
  */
 class ImportDirective extends NamespaceDirective {
   static Comparator<ImportDirective> COMPARATOR = (ImportDirective import1, ImportDirective import2) {
+    //
+    // uri
+    //
     StringLiteral uri1 = import1.uri;
     StringLiteral uri2 = import2.uri;
     String uriStr1 = uri1.stringValue;
     String uriStr2 = uri2.stringValue;
     if (uriStr1 != null || uriStr2 != null) {
       if (uriStr1 == null) {
         return -1;
       } else if (uriStr2 == null) {
         return 1;
       } else {
         int compare = uriStr1.compareTo(uriStr2);
         if (compare != 0) {
           return compare;
         }
       }
     }
+    //
+    // as
+    //
     SimpleIdentifier prefix1 = import1.prefix;
     SimpleIdentifier prefix2 = import2.prefix;
     String prefixStr1 = prefix1 != null ? prefix1.name : null;
     String prefixStr2 = prefix2 != null ? prefix2.name : null;
     if (prefixStr1 != null || prefixStr2 != null) {
       if (prefixStr1 == null) {
         return -1;
       } else if (prefixStr2 == null) {
         return 1;
       } else {
         int compare = prefixStr1.compareTo(prefixStr2);
         if (compare != 0) {
           return compare;
         }
       }
     }
+    //
+    // hides and shows
+    //
     NodeList<Combinator> combinators1 = import1.combinators;
     List<String> allHides1 = new List<String>();
     List<String> allShows1 = new List<String>();
     for (Combinator combinator in combinators1) {
       if (combinator is HideCombinator) {
         NodeList<SimpleIdentifier> hides = combinator.hiddenNames;
         for (SimpleIdentifier simpleIdentifier in hides) {
           allHides1.add(simpleIdentifier.name);
         }
       } else {
@@ skipping 12 matching lines @@
         for (SimpleIdentifier simpleIdentifier in hides) {
           allHides2.add(simpleIdentifier.name);
         }
       } else {
         NodeList<SimpleIdentifier> shows = (combinator as ShowCombinator).shownNames;
         for (SimpleIdentifier simpleIdentifier in shows) {
           allShows2.add(simpleIdentifier.name);
         }
       }
     }
+    // test lengths of combinator lists first
     if (allHides1.length != allHides2.length) {
       return allHides1.length - allHides2.length;
     }
     if (allShows1.length != allShows2.length) {
       return allShows1.length - allShows2.length;
     }
+    // next ensure that the lists are equivalent
     if (!javaCollectionContainsAll(allHides1, allHides2)) {
       return -1;
     }
     if (!javaCollectionContainsAll(allShows1, allShows2)) {
       return -1;
     }
     return 0;
   };
 
   /**
@@ skipping 2076 matching lines @@
   /**
    * Set the name of the parameter being declared to the given identifier.
    *
    * @param identifier the name of the parameter being declared
    */
   void set identifier(SimpleIdentifier identifier) {
     this._identifier = becomeParentOf(identifier);
   }
 
   void visitChildren(ASTVisitor visitor) {
+    //
+    // Note that subclasses are responsible for visiting the identifier because they often need to
+    // visit other nodes before visiting the identifier.
+    //
     if (commentIsBeforeAnnotations()) {
       safelyVisitChild(_comment, visitor);
       _metadata.accept(visitor);
     } else {
       for (ASTNode child in sortedCommentAndAnnotations) {
         child.accept(visitor);
       }
     }
   }
 
@@ skipping 1328 matching lines @@
    *
    * Note that [inGetterContext] and [inSetterContext] are not opposites, nor are
    * they mutually exclusive. In other words, it is possible for both methods to return `true`
    * when invoked on the same node.
    *
    * @return `true` if this expression is in a context where a getter will be invoked
    */
   bool inGetterContext() {
     ASTNode parent = this.parent;
     ASTNode target = this;
+    // skip prefix
     if (parent is PrefixedIdentifier) {
       PrefixedIdentifier prefixed = parent as PrefixedIdentifier;
       if (identical(prefixed.prefix, this)) {
         return true;
       }
       parent = prefixed.parent;
       target = prefixed;
     } else if (parent is PropertyAccess) {
       PropertyAccess access = parent as PropertyAccess;
       if (identical(access.target, this)) {
         return true;
       }
       parent = access.parent;
       target = access;
     }
+    // skip label
     if (parent is Label) {
       return false;
     }
+    // analyze usage
     if (parent is AssignmentExpression) {
       AssignmentExpression expr = parent as AssignmentExpression;
       if (identical(expr.leftHandSide, target) && identical(expr.operator.type, TokenType.EQ)) {
         return false;
       }
     }
     return true;
   }
 
   /**
    * Return `true` if this expression is computing a left-hand value.
    *
    * Note that [inGetterContext] and [inSetterContext] are not opposites, nor are
    * they mutually exclusive. In other words, it is possible for both methods to return `true`
    * when invoked on the same node.
    *
    * @return `true` if this expression is in a context where a setter will be invoked
    */
   bool inSetterContext() {
     ASTNode parent = this.parent;
     ASTNode target = this;
+    // skip prefix
     if (parent is PrefixedIdentifier) {
       PrefixedIdentifier prefixed = parent as PrefixedIdentifier;
+      // if this is the prefix, then return false
       if (identical(prefixed.prefix, this)) {
         return false;
       }
       parent = prefixed.parent;
       target = prefixed;
     } else if (parent is PropertyAccess) {
       PropertyAccess access = parent as PropertyAccess;
       if (identical(access.target, this)) {
         return false;
       }
       parent = access.parent;
       target = access;
     }
+    // analyze usage
     if (parent is PrefixExpression) {
       return (parent as PrefixExpression).operator.type.isIncrementOperator;
     } else if (parent is PostfixExpression) {
       return true;
     } else if (parent is AssignmentExpression) {
       return identical((parent as AssignmentExpression).leftHandSide, target);
     }
     return false;
   }
 
@@ skipping 2052 matching lines @@
     Object leftOperand = node.leftOperand.accept(this);
     if (identical(leftOperand, NOT_A_CONSTANT)) {
       return leftOperand;
     }
     Object rightOperand = node.rightOperand.accept(this);
     if (identical(rightOperand, NOT_A_CONSTANT)) {
       return rightOperand;
     }
     while (true) {
       if (node.operator.type == TokenType.AMPERSAND) {
+        // integer or {@code null}
         if (leftOperand is int && rightOperand is int) {
           return leftOperand & rightOperand;
         }
       } else if (node.operator.type == TokenType.AMPERSAND_AMPERSAND) {
+        // boolean or {@code null}
         if (leftOperand is bool && rightOperand is bool) {
           return leftOperand && rightOperand;
         }
       } else if (node.operator.type == TokenType.BANG_EQ) {
+        // numeric, string, boolean, or {@code null}
         if (leftOperand is bool && rightOperand is bool) {
           return leftOperand != rightOperand;
         } else if (leftOperand is int && rightOperand is int) {
           return leftOperand != rightOperand;
         } else if (leftOperand is double && rightOperand is double) {
           return leftOperand != rightOperand;
         } else if (leftOperand is String && rightOperand is String) {
           return leftOperand != rightOperand;
         }
       } else if (node.operator.type == TokenType.BAR) {
+        // integer or {@code null}
         if (leftOperand is int && rightOperand is int) {
           return leftOperand | rightOperand;
         }
       } else if (node.operator.type == TokenType.BAR_BAR) {
+        // boolean or {@code null}
         if (leftOperand is bool && rightOperand is bool) {
           return leftOperand || rightOperand;
         }
       } else if (node.operator.type == TokenType.CARET) {
+        // integer or {@code null}
         if (leftOperand is int && rightOperand is int) {
           return leftOperand ^ rightOperand;
         }
       } else if (node.operator.type == TokenType.EQ_EQ) {
+        // numeric, string, boolean, or {@code null}
         if (leftOperand is bool && rightOperand is bool) {
           return identical(leftOperand, rightOperand);
         } else if (leftOperand is int && rightOperand is int) {
           return leftOperand == rightOperand;
         } else if (leftOperand is double && rightOperand is double) {
           return leftOperand == rightOperand;
         } else if (leftOperand is String && rightOperand is String) {
           return leftOperand == rightOperand;
         }
       } else if (node.operator.type == TokenType.GT) {
+        // numeric or {@code null}
         if (leftOperand is int && rightOperand is int) {
           return leftOperand.compareTo(rightOperand) > 0;
         } else if (leftOperand is double && rightOperand is double) {
           return leftOperand.compareTo(rightOperand) > 0;
         }
       } else if (node.operator.type == TokenType.GT_EQ) {
+        // numeric or {@code null}
         if (leftOperand is int && rightOperand is int) {
           return leftOperand.compareTo(rightOperand) >= 0;
         } else if (leftOperand is double && rightOperand is double) {
           return leftOperand.compareTo(rightOperand) >= 0;
         }
       } else if (node.operator.type == TokenType.GT_GT) {
+        // integer or {@code null}
         if (leftOperand is int && rightOperand is int) {
           return leftOperand >> rightOperand;
         }
       } else if (node.operator.type == TokenType.LT) {
+        // numeric or {@code null}
         if (leftOperand is int && rightOperand is int) {
           return leftOperand.compareTo(rightOperand) < 0;
         } else if (leftOperand is double && rightOperand is double) {
           return leftOperand.compareTo(rightOperand) < 0;
         }
       } else if (node.operator.type == TokenType.LT_EQ) {
+        // numeric or {@code null}
         if (leftOperand is int && rightOperand is int) {
           return leftOperand.compareTo(rightOperand) <= 0;
         } else if (leftOperand is double && rightOperand is double) {
           return leftOperand.compareTo(rightOperand) <= 0;
         }
       } else if (node.operator.type == TokenType.LT_LT) {
+        // integer or {@code null}
         if (leftOperand is int && rightOperand is int) {
           return leftOperand << rightOperand;
         }
       } else if (node.operator.type == TokenType.MINUS) {
+        // numeric or {@code null}
         if (leftOperand is int && rightOperand is int) {
           return leftOperand - rightOperand;
         } else if (leftOperand is double && rightOperand is double) {
           return leftOperand - rightOperand;
         }
       } else if (node.operator.type == TokenType.PERCENT) {
+        // numeric or {@code null}
         if (leftOperand is int && rightOperand is int) {
           return leftOperand.remainder(rightOperand);
         } else if (leftOperand is double && rightOperand is double) {
           return leftOperand % rightOperand;
         }
       } else if (node.operator.type == TokenType.PLUS) {
+        // numeric or {@code null}
         if (leftOperand is int && rightOperand is int) {
           return leftOperand + rightOperand;
         } else if (leftOperand is double && rightOperand is double) {
           return leftOperand + rightOperand;
         }
       } else if (node.operator.type == TokenType.STAR) {
+        // numeric or {@code null}
         if (leftOperand is int && rightOperand is int) {
           return leftOperand * rightOperand;
         } else if (leftOperand is double && rightOperand is double) {
           return leftOperand * rightOperand;
         }
       } else if (node.operator.type == TokenType.SLASH) {
+        // numeric or {@code null}
         if (leftOperand is int && rightOperand is int) {
           if (rightOperand != 0) {
             return leftOperand ~/ rightOperand;
           } else {
             return leftOperand.toDouble() / rightOperand.toDouble();
           }
         } else if (leftOperand is double && rightOperand is double) {
           return leftOperand / rightOperand;
         }
       } else if (node.operator.type == TokenType.TILDE_SLASH) {
+        // numeric or {@code null}
         if (leftOperand is int && rightOperand is int) {
           if (rightOperand != 0) {
             return leftOperand ~/ rightOperand;
           } else {
             return 0;
           }
         } else if (leftOperand is double && rightOperand is double) {
           return leftOperand ~/ rightOperand;
         }
       }
       break;
     }
+    // TODO(brianwilkerson) This doesn't handle numeric conversions.
     return visitExpression(node);
   }
 
   Object visitBooleanLiteral(BooleanLiteral node) => node.value ? true : false;
 
   Object visitDoubleLiteral(DoubleLiteral node) => node.value;
 
   Object visitIntegerLiteral(IntegerLiteral node) => node.value;
 
   Object visitInterpolationExpression(InterpolationExpression node) {
@@ skipping 83 matching lines @@
       Object value = element.accept(this);
       if (identical(value, NOT_A_CONSTANT)) {
         return value;
       }
       builder.append(value);
     }
     return builder.toString();
   }
 
   Object visitSymbolLiteral(SymbolLiteral node) {
+    // TODO(brianwilkerson) This isn't optimal because a Symbol is not a String.
     JavaStringBuilder builder = new JavaStringBuilder();
     for (Token component in node.components) {
       if (builder.length > 0) {
         builder.appendChar(0x2E);
       }
       builder.append(component.lexeme);
     }
     return builder.toString();
   }
 
   /**
    * Return the constant value of the static constant represented by the given element.
    *
    * @param element the element whose value is to be returned
    * @return the constant value of the static constant
    */
   Object getConstantValue(Element element) {
+    // TODO(brianwilkerson) Implement this
     if (element is FieldElement) {
       FieldElement field = element;
       if (field.isStatic && field.isConst) {
       }
     }
     return NOT_A_CONSTANT;
   }
 }
 
 /**
@@ skipping 15 matching lines @@
   }
 
   /**
    * Locate the [Element] associated with the given [ASTNode] and offset.
    *
    * @param node the node (not `null`)
    * @param offset the offset relative to source
    * @return the associated element, or `null` if none is found
    */
   static Element locate2(ASTNode node, int offset) {
+    // try to get Element from node
     {
       Element nodeElement = locate(node);
       if (nodeElement != null) {
         return nodeElement;
       }
     }
+    // try to get Angular specific Element
     {
       Element element = null;
       if (element != null) {
         return element;
       }
     }
+    // no Element
     return null;
   }
 }
 
 /**
  * Visitor that maps nodes to elements.
  */
 class ElementLocator_ElementMapper extends GeneralizingASTVisitor<Element> {
   Element visitAssignmentExpression(AssignmentExpression node) => node.bestElement;
 
   Element visitBinaryExpression(BinaryExpression node) => node.bestElement;
 
   Element visitClassDeclaration(ClassDeclaration node) => node.element;
 
   Element visitCompilationUnit(CompilationUnit node) => node.element;
 
   Element visitConstructorDeclaration(ConstructorDeclaration node) => node.element;
 
   Element visitFunctionDeclaration(FunctionDeclaration node) => node.element;
 
   Element visitIdentifier(Identifier node) {
     ASTNode parent = node.parent;
+    // Extra work to map Constructor Declarations to their associated Constructor Elements
     if (parent is ConstructorDeclaration) {
       ConstructorDeclaration decl = parent;
       Identifier returnType = decl.returnType;
       if (identical(returnType, node)) {
         SimpleIdentifier name = decl.name;
         if (name != null) {
           return name.bestElement;
         }
         Element element = node.bestElement;
         if (element is ClassElement) {
@@ skipping 401 matching lines @@
       return null;
     }
     if (start > _endOffset) {
       return null;
     }
     try {
       node.visitChildren(this);
     } on NodeLocator_NodeFoundException catch (exception) {
       throw exception;
     } on JavaException catch (exception) {
+      // Ignore the exception and proceed in order to visit the rest of the structure.
       AnalysisEngine.instance.logger.logInformation2("Exception caught while traversing an AST structure.", exception);
     }
     if (start <= _startOffset && _endOffset <= end) {
       _foundNode = node;
       throw new NodeLocator_NodeFoundException();
     }
     return null;
   }
 }
 
@@ skipping 3215 matching lines @@
 
   ScriptTag visitScriptTag(ScriptTag node) => new ScriptTag(map(node.scriptTag));
 
   ShowCombinator visitShowCombinator(ShowCombinator node) => new ShowCombinator(map(node.keyword), clone5(node.shownNames));
 
   SimpleFormalParameter visitSimpleFormalParameter(SimpleFormalParameter node) => new SimpleFormalParameter(clone4(node.documentationComment), clone5(node.metadata), map(node.keyword), clone4(node.type), clone4(node.identifier));
 
   SimpleIdentifier visitSimpleIdentifier(SimpleIdentifier node) {
     Token mappedToken = map(node.token);
     if (mappedToken == null) {
+      // This only happens for SimpleIdentifiers created by the parser as part of scanning
+      // documentation comments (the tokens for those identifiers are not in the original token
+      // stream and hence do not get copied). This extra check can be removed if the scanner is
+      // changed to scan documentation comments for the parser.
       mappedToken = node.token;
     }
     SimpleIdentifier copy = new SimpleIdentifier(mappedToken);
     copy.auxiliaryElements = node.auxiliaryElements;
     copy.propagatedElement = node.propagatedElement;
     copy.propagatedType = node.propagatedType;
     copy.staticElement = node.staticElement;
     copy.staticType = node.staticType;
     return copy;
   }
@@ skipping 269 matching lines @@
       if (stmt is VariableDeclarationStatement) {
         addVariables(stmt.variables.variables);
       } else if (stmt is FunctionDeclarationStatement && !_referenceIsWithinLocalFunction) {
         addToScope(stmt.functionDeclaration.name);
       }
     }
   }
 
   bool isInRange(ASTNode node) {
     if (_position < 0) {
+      // if source position is not set then all nodes are in range
       return true;
     }
     return node.end < _position;
   }
 }
 /**
  * Instances of the class {@code NodeList} represent a list of AST nodes that have a common parent.
  */
 class NodeList<E extends ASTNode> extends Object with ListMixin<E> {
   /**
@@ skipping 104 matching lines @@
   }
   void operator[]=(int index, E node) {
     if (index < 0 || index >= _elements.length) {
       throw new RangeError("Index: ${index}, Size: ${_elements.length}");
     }
     owner.becomeParentOf(node);
     _elements[index] = node;
   }
   int get length => _elements.length;
 }