Issue 8742. Preserve leading line comments during java2dart translation.

pkg/analyzer/lib/src/generated/html.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.html;
 
 import 'dart:collection';
@@ skipping 259 matching lines @@
   static Element getElement2(HtmlUnit htmlUnit, int offset) {
     Expression expression = getExpression(htmlUnit, offset);
     return getElement(expression);
   }
 
   /**
    * Returns the [Element] to open when requested at the given [Expression].
    */
   static Element getElementToOpen(HtmlUnit htmlUnit, Expression expression) {
     Element element = getElement(expression);
+    // special cases for Angular
     if (isAngular(htmlUnit)) {
+      // replace artificial controller variable Element with controller ClassElement
       if (element is VariableElement) {
         VariableElement variable = element as VariableElement;
         Type2 type = variable.type;
         if (variable.nameOffset == 0 && type is InterfaceType) {
           element = type.element;
         }
       }
     }
+    // done
     return element;
   }
 
   /**
    * Returns the [Expression] that is part of the given [HtmlUnit] and encloses the
    * given offset.
    */
   static Expression getExpression(HtmlUnit htmlUnit, int offset) {
     if (htmlUnit == null) {
       return null;
@@ skipping 288 matching lines @@
    *
    * @param children the nodes that will become the children of this node
    * @return the nodes that were made children of this node
    */
   List becomeParentOf(List children) {
     if (children != null) {
       for (JavaIterator iter = new JavaIterator(children); iter.hasNext;) {
         XmlNode node = iter.next();
         node.parent = this;
       }
+      // This will create ArrayList for exactly given number of elements.
       return new List.from(children);
     }
     return children;
   }
 
   /**
    * Make this node the parent of the given child node.
    *
    * @param child the node that will become a child of this node
    * @return the node that was made a child of this node
@@ skipping 184 matching lines @@
 
   /**
    * Record the fact that we are at the beginning of a new line in the source.
    */
   void recordStartOfLine() {
     _lineStarts.add(offset);
   }
 
   void appendEofToken() {
     Token eofToken = new Token.con1(TokenType.EOF, offset);
+    // The EOF token points to itself so that there is always infinite look-ahead.
     eofToken.setNext(eofToken);
     _tail = _tail.setNext(eofToken);
   }
 
   Token emit(Token token) {
     _tail.setNext(token);
     _tail = token;
     return token;
   }
 
@@ skipping 23 matching lines @@
     bool inBrackets = false;
     String endPassThrough = null;
     int c = advance();
     while (c >= 0) {
       int start = offset;
       if (c == 0x3C) {
         c = advance();
         if (c == 0x21) {
           c = advance();
           if (c == 0x2D && peek() == 0x2D) {
+            // handle a comment
             c = advance();
             int dashCount = 1;
             while (c >= 0) {
               if (c == 0x2D) {
                 dashCount++;
               } else if (c == 0x3E && dashCount >= 2) {
                 c = advance();
                 break;
               } else {
                 dashCount = 0;
               }
               c = recordStartOfLineAndAdvance(c);
             }
             emit3(TokenType.COMMENT, start, -1);
+            // Capture <!--> and <!---> as tokens but report an error
             if (_tail.length < 7) {
             }
           } else {
+            // handle a declaration
             while (c >= 0) {
               if (c == 0x3E) {
                 c = advance();
                 break;
               }
               c = recordStartOfLineAndAdvance(c);
             }
             emit3(TokenType.DECLARATION, start, -1);
             if (!_tail.lexeme.endsWith(">")) {
             }
           }
         } else if (c == 0x3F) {
+          // handle a directive
           while (c >= 0) {
             if (c == 0x3F) {
               c = advance();
               if (c == 0x3E) {
                 c = advance();
                 break;
               }
             } else {
               c = recordStartOfLineAndAdvance(c);
             }
           }
           emit3(TokenType.DIRECTIVE, start, -1);
           if (_tail.length < 4) {
           }
         } else if (c == 0x2F) {
           emit2(TokenType.LT_SLASH, start);
           inBrackets = true;
           c = advance();
         } else {
           inBrackets = true;
           emit2(TokenType.LT, start);
+          // ignore whitespace in braces
           while (Character.isWhitespace(c)) {
             c = recordStartOfLineAndAdvance(c);
           }
+          // get tag
           if (Character.isLetterOrDigit(c)) {
             int tagStart = offset;
             c = advance();
             while (Character.isLetterOrDigit(c) || c == 0x2D || c == 0x5F) {
               c = advance();
             }
             emit3(TokenType.TAG, tagStart, -1);
+            // check tag against passThrough elements
             String tag = _tail.lexeme;
             for (String str in _passThroughElements) {
               if (str == tag) {
                 endPassThrough = "</${str}>";
                 break;
               }
             }
           }
         }
       } else if (c == 0x3E) {
         emit2(TokenType.GT, start);
         inBrackets = false;
         c = advance();
+        // if passThrough != null, read until we match it
         if (endPassThrough != null) {
           bool endFound = false;
           int len = endPassThrough.length;
           int firstC = endPassThrough.codeUnitAt(0);
           int index = 0;
           int nextC = firstC;
           while (c >= 0) {
             if (c == nextC) {
               index++;
               if (index == len) {
@@ skipping 26 matching lines @@
         emit2(TokenType.SLASH_GT, start);
         inBrackets = false;
         c = advance();
       } else if (!inBrackets) {
         c = recordStartOfLineAndAdvance(c);
         while (c != 0x3C && c >= 0) {
           c = recordStartOfLineAndAdvance(c);
         }
         emit3(TokenType.TEXT, start, -1);
       } else if (c == 0x22 || c == 0x27) {
+        // read a string
         int endQuote = c;
         c = advance();
         while (c >= 0) {
           if (c == endQuote) {
             c = advance();
             break;
           }
           c = recordStartOfLineAndAdvance(c);
         }
         emit3(TokenType.STRING, start, -1);
       } else if (c == 0x3D) {
+        // a non-char token
         emit2(TokenType.EQ, start);
         c = advance();
       } else if (Character.isWhitespace(c)) {
+        // ignore whitespace in braces
         do {
           c = recordStartOfLineAndAdvance(c);
         } while (Character.isWhitespace(c));
       } else if (Character.isLetterOrDigit(c)) {
         c = advance();
         while (Character.isLetterOrDigit(c) || c == 0x2D || c == 0x5F) {
           c = advance();
         }
         emit3(TokenType.TAG, start, -1);
       } else {
+        // a non-char token
         emit3(TokenType.TEXT, start, 0);
         c = advance();
       }
     }
   }
 }
 
 /**
  * Instances of `HtmlScanResult` hold the result of scanning an HTML file.
  *
@@ skipping 323 matching lines @@
 
   /**
    * Answer the lexeme for the value token without the leading and trailing quotes.
    *
    * @return the text or `null` if the value is not specified
    */
   String get text {
     if (_value == null) {
       return null;
     }
+    //TODO (danrubel): replace HTML character encodings with the actual characters
     String text = _value.lexeme;
     int len = text.length;
     if (len > 0) {
       if (text.codeUnitAt(0) == 0x22) {
         if (len > 1 && text.codeUnitAt(len - 1) == 0x22) {
           return text.substring(1, len - 1);
         } else {
           return text.substring(1);
         }
       } else if (text.codeUnitAt(0) == 0x27) {
@@ skipping 217 matching lines @@
    * @return the list of tag nodes found (not `null`, contains no `null`)
    */
   List<XmlTagNode> parseTopTagNodes(Token firstToken) {
     _currentToken = firstToken;
     List<XmlTagNode> tagNodes = new List<XmlTagNode>();
     while (true) {
       while (true) {
         if (_currentToken.type == TokenType.LT) {
           tagNodes.add(parseTagNode());
         } else if (_currentToken.type == TokenType.DECLARATION || _currentToken.type == TokenType.DIRECTIVE || _currentToken.type == TokenType.COMMENT) {
+          // ignored tokens
           _currentToken = _currentToken.next;
         } else if (_currentToken.type == TokenType.EOF) {
           return tagNodes;
         } else {
           reportUnexpectedToken();
           _currentToken = _currentToken.next;
         }
         break;
       }
     }
@@ skipping 19 matching lines @@
     return token;
   }
 
   /**
    * Parse the token stream for an attribute. This method advances the current token over the
    * attribute, but should not be called if the [currentToken] is not [TokenType#TAG].
    *
    * @return the attribute (not `null`)
    */
   XmlAttributeNode parseAttribute() {
+    // Assume the current token is a tag
     Token name = _currentToken;
     _currentToken = _currentToken.next;
+    // Equals sign
     Token equals;
     if (identical(_currentToken.type, TokenType.EQ)) {
       equals = _currentToken;
       _currentToken = _currentToken.next;
     } else {
       reportUnexpectedToken();
       equals = insertSyntheticToken(TokenType.EQ);
     }
+    // String value
     Token value;
     if (identical(_currentToken.type, TokenType.STRING)) {
       value = _currentToken;
       _currentToken = _currentToken.next;
     } else {
       reportUnexpectedToken();
       value = insertSyntheticToken(TokenType.STRING);
     }
     return createAttributeNode(name, equals, value);
   }
@@ skipping 37 matching lines @@
       return XmlTagNode.NO_TAG_NODES;
     }
     List<XmlTagNode> nodes = new List<XmlTagNode>();
     while (true) {
       while (true) {
         if (_currentToken.type == TokenType.LT) {
           nodes.add(parseTagNode());
         } else if (_currentToken.type == TokenType.LT_SLASH || _currentToken.type == TokenType.EOF) {
           return nodes;
         } else if (_currentToken.type == TokenType.COMMENT) {
+          // ignored token
           _currentToken = _currentToken.next;
         } else {
           reportUnexpectedToken();
           _currentToken = _currentToken.next;
         }
         break;
       }
     }
   }
 
   /**
    * Parse the token stream for the next tag node. This method advances current token over the
    * parsed tag node, but should only be called if the current token is [TokenType#LT]
    *
    * @return the tag node or `null` if none found
    */
   XmlTagNode parseTagNode() {
+    // Assume that the current node is a tag node start TokenType#LT
     Token nodeStart = _currentToken;
     _currentToken = _currentToken.next;
+    // Get the tag or create a synthetic tag and report an error
     Token tag;
     if (identical(_currentToken.type, TokenType.TAG)) {
       tag = _currentToken;
       _currentToken = _currentToken.next;
     } else {
       reportUnexpectedToken();
       tag = insertSyntheticToken(TokenType.TAG);
     }
+    // Parse the attributes
     List<XmlAttributeNode> attributes = parseAttributes();
+    // Token ending attribute list
     Token attributeEnd;
     if (identical(_currentToken.type, TokenType.GT) || identical(_currentToken.type, TokenType.SLASH_GT)) {
       attributeEnd = _currentToken;
       _currentToken = _currentToken.next;
     } else {
       reportUnexpectedToken();
       attributeEnd = insertSyntheticToken(TokenType.SLASH_GT);
     }
+    // If the node has no children, then return the node
     if (identical(attributeEnd.type, TokenType.SLASH_GT) || isSelfClosing(tag)) {
       return createTagNode(nodeStart, tag, attributes, attributeEnd, XmlTagNode.NO_TAG_NODES, _currentToken, null, attributeEnd);
     }
+    // Parse the child tag nodes
     List<XmlTagNode> tagNodes = parseChildTagNodes();
+    // Token ending child tag nodes
     Token contentEnd;
     if (identical(_currentToken.type, TokenType.LT_SLASH)) {
       contentEnd = _currentToken;
       _currentToken = _currentToken.next;
     } else {
+      // TODO (danrubel): handle self closing HTML elements by inserting synthetic tokens
+      // but not reporting an error
       reportUnexpectedToken();
       contentEnd = insertSyntheticToken(TokenType.LT_SLASH);
     }
+    // Closing tag
     Token closingTag;
     if (identical(_currentToken.type, TokenType.TAG)) {
       closingTag = _currentToken;
       _currentToken = _currentToken.next;
     } else {
       reportUnexpectedToken();
       closingTag = insertSyntheticToken(TokenType.TAG);
     }
+    // Token ending node
     Token nodeEnd;
     if (identical(_currentToken.type, TokenType.GT)) {
       nodeEnd = _currentToken;
       _currentToken = _currentToken.next;
     } else {
       reportUnexpectedToken();
       nodeEnd = insertSyntheticToken(TokenType.GT);
     }
     return createTagNode(nodeStart, tag, attributes, attributeEnd, tagNodes, contentEnd, closingTag, nodeEnd);
   }
@@ skipping 155 matching lines @@
    * representation of any child tag nodes ([getTagNodes]). Whitespace between '&lt;',
    * '&lt;/', and '>', '/>' is discarded, but all other whitespace is preserved.
    *
    * @return the content (not `null`)
    */
   String get content {
     Token token = attributeEnd.next;
     if (identical(token, contentEnd)) {
       return "";
     }
+    //TODO (danrubel): handle CDATA and replace HTML character encodings with the actual characters
     String content = token.lexeme;
     token = token.next;
     if (identical(token, contentEnd)) {
       return content;
     }
     JavaStringBuilder buffer = new JavaStringBuilder();
     while (token != contentEnd) {
       buffer.append(token.lexeme);
       token = token.next;
     }
@@ skipping 270 matching lines @@
     }
     super.element = element;
   }
 
   void visitChildren(XmlVisitor visitor) {
     for (XmlTagNode node in _tagNodes) {
       node.accept(visitor);
     }
   }
 }