[html5lib] triple slash comment style

pkg/third_party/html5lib/lib/dom.dart

-/**
- * A simple tree API that results from parsing html. Intended to be compatible
- * with dart:html, but right now it resembles the classic JS DOM.
- */
+/// A simple tree API that results from parsing html. Intended to be compatible
+/// with dart:html, but right now it resembles the classic JS DOM.
 library dom;
 
 import 'dart:collection';
 import 'package:source_maps/span.dart' show FileSpan;
 
 import 'src/constants.dart';
 import 'src/list_proxy.dart';
 import 'src/token.dart';
 import 'src/tokenizer.dart';
 import 'src/utils.dart';
 import 'dom_parsing.dart';
 import 'parser.dart';
 
 // TODO(jmesserly): this needs to be replaced by an AttributeMap for attributes
 // that exposes namespace info.
 class AttributeName implements Comparable {
-  /** The namespace prefix, e.g. `xlink`. */
+  /// The namespace prefix, e.g. `xlink`.
   final String prefix;
 
-  /** The attribute name, e.g. `title`. */
+  /// The attribute name, e.g. `title`.
   final String name;
 
-  /** The namespace url, e.g. `http://www.w3.org/1999/xlink` */
+  /// The namespace url, e.g. `http://www.w3.org/1999/xlink`
   final String namespace;
 
   const AttributeName(this.prefix, this.name, this.namespace);
 
   String toString() {
     // Implement:
     // http://www.whatwg.org/specs/web-apps/current-work/multipage/the-end.html#serializing-html-fragments
     // If we get here we know we are xml, xmlns, or xlink, because of
     // [HtmlParser.adjustForeignAttriubtes] is the only place we create
     // an AttributeName.
@@ skipping 17 matching lines @@
     if (cmp != 0) return cmp;
     return namespace.compareTo(other.namespace);
   }
 
   bool operator ==(x) {
     if (x is! AttributeName) return false;
     return prefix == x.prefix && name == x.name && namespace == x.namespace;
   }
 }
 
-/** Really basic implementation of a DOM-core like Node. */
+/// Really basic implementation of a DOM-core like Node.
 abstract class Node {
   static const int ATTRIBUTE_NODE = 2;
   static const int CDATA_SECTION_NODE = 4;
   static const int COMMENT_NODE = 8;
   static const int DOCUMENT_FRAGMENT_NODE = 11;
   static const int DOCUMENT_NODE = 9;
   static const int DOCUMENT_TYPE_NODE = 10;
   static const int ELEMENT_NODE = 1;
   static const int ENTITY_NODE = 6;
   static const int ENTITY_REFERENCE_NODE = 5;
   static const int NOTATION_NODE = 12;
   static const int PROCESSING_INSTRUCTION_NODE = 7;
   static const int TEXT_NODE = 3;
 
   // TODO(jmesserly): this should be on Element
-  /** The tag name associated with the node. */
+  /// The tag name associated with the node.
   final String tagName;
 
-  /** The parent of the current node (or null for the document node). */
+  /// The parent of the current node (or null for the document node).
   Node parent;
 
   // TODO(jmesserly): should move to Element.
-  /**
-   * A map holding name, value pairs for attributes of the node.
-   *
-   * Note that attribute order needs to be stable for serialization, so we use a
-   * LinkedHashMap. Each key is a [String] or [AttributeName].
-   */
+  /// A map holding name, value pairs for attributes of the node.
+  ///
+  /// Note that attribute order needs to be stable for serialization, so we use a

[Siggi Cherem (dart-lang), 2014/02/24 23:03:29]

80

[Jennifer Messerly, 2014/02/25 00:32:08]

funny. this was the line I was iterating on when I was futzing with the script.
Must've reverted everything and forgot to fix it >.<

+  /// LinkedHashMap. Each key is a [String] or [AttributeName].
   LinkedHashMap<dynamic, String> attributes = new LinkedHashMap();
 
-  /**
-   * A list of child nodes of the current node. This must
-   * include all elements but not necessarily other node types.
-   */
+  /// A list of child nodes of the current node. This must
+  /// include all elements but not necessarily other node types.
   final NodeList nodes = new NodeList._();
 
   List<Element> _elements;
 
   // TODO(jmesserly): consider using an Expando for this, and put it in
   // dom_parsing. Need to check the performance affect.
-  /** The source span of this node, if it was created by the [HtmlParser]. */
+  /// The source span of this node, if it was created by the [HtmlParser].
   FileSpan sourceSpan;
 
-  /** The attribute spans if requested. Otherwise null. */
+  /// The attribute spans if requested. Otherwise null.
   LinkedHashMap<dynamic, FileSpan> _attributeSpans;
   LinkedHashMap<dynamic, FileSpan> _attributeValueSpans;
 
   Node(this.tagName) {
     nodes._parent = this;
   }
 
-  /**
-   * If [sourceSpan] is available, this contains the spans of each attribute.
-   * The span of an attribute is the entire attribute, including the name and
-   * quotes (if any). For example, the span of "attr" in `<a attr="value">`
-   * would be the text `attr="value"`.
-   */
+  /// If [sourceSpan] is available, this contains the spans of each attribute.
+  /// The span of an attribute is the entire attribute, including the name and
+  /// quotes (if any). For example, the span of "attr" in `<a attr="value">`
+  /// would be the text `attr="value"`.
   LinkedHashMap<dynamic, FileSpan> get attributeSpans {
     _ensureAttributeSpans();
     return _attributeSpans;
   }
 
-  /**
-   * If [sourceSpan] is available, this contains the spans of each attribute's
-   * value. Unlike [attributeSpans], this span will inlcude only the value.
-   * For example, the value span of "attr" in `<a attr="value">` would be the
-   * text `value`.
-   */
+  /// If [sourceSpan] is available, this contains the spans of each attribute's
+  /// value. Unlike [attributeSpans], this span will inlcude only the value.
+  /// For example, the value span of "attr" in `<a attr="value">` would be the
+  /// text `value`.
   LinkedHashMap<dynamic, FileSpan> get attributeValueSpans {
     _ensureAttributeSpans();
     return _attributeValueSpans;
   }
 
   List<Element> get children {
     if (_elements == null) {
       _elements = new FilteredElementList(this);
     }
     return _elements;
   }
 
   // TODO(jmesserly): needs to support deep clone.
-  /**
-   * Return a shallow copy of the current node i.e. a node with the same
-   * name and attributes but with no parent or child nodes.
-   */
+  /// Return a shallow copy of the current node i.e. a node with the same
+  /// name and attributes but with no parent or child nodes.
   Node clone();
 
   String get namespace => null;
 
   int get nodeType;
 
-  /** *Deprecated* use [text], [Text.data] or [Comment.data]. */
+  /// *Deprecated* use [text], [Text.data] or [Comment.data].
   @deprecated String get value => null;
 
-  /** *Deprecated* use [nodeType]. */
+  /// *Deprecated* use [nodeType].
   @deprecated int get $dom_nodeType => nodeType;
 
   String get outerHtml {
     var str = new StringBuffer();
     _addOuterHtml(str);
     return str.toString();
   }
 
   String get innerHtml {
     var str = new StringBuffer();
@@ skipping 25 matching lines @@
   String toString() => tagName;
 
   Node remove() {
     // TODO(jmesserly): is parent == null an error?
     if (parent != null) {
       parent.nodes.remove(this);
     }
     return this;
   }
 
-  /**
-   * Insert [node] as a child of the current node, before [refNode] in the
-   * list of child nodes. Raises [UnsupportedOperationException] if [refNode]
-   * is not a child of the current node. If refNode is null, this adds to the
-   * end of the list.
-   */
+  /// Insert [node] as a child of the current node, before [refNode] in the
+  /// list of child nodes. Raises [UnsupportedOperationException] if [refNode]
+  /// is not a child of the current node. If refNode is null, this adds to the
+  /// end of the list.
   void insertBefore(Node node, Node refNode) {
     if (refNode == null) {
       nodes.add(node);
     } else {
       nodes.insert(nodes.indexOf(refNode), node);
     }
   }
 
-  /** Replaces this node with another node. */
+  /// Replaces this node with another node.
   Node replaceWith(Node otherNode) {
     if (parent == null) {
       throw new UnsupportedError('Node must have a parent to replace it.');
     }
     parent.nodes[parent.nodes.indexOf(this)] = otherNode;
     return this;
   }
 
   // TODO(jmesserly): should this be a property or remove?
-  /** Return true if the node has children or text. */
+  /// Return true if the node has children or text.
   bool hasContent() => nodes.length > 0;
 
   Pair<String, String> get nameTuple {
     var ns = namespace != null ? namespace : Namespaces.html;
     return new Pair(ns, tagName);
   }
 
-  /**
-   * Move all the children of the current node to [newParent].
-   * This is needed so that trees that don't store text as nodes move the
-   * text in the correct way.
-   */
+  /// Move all the children of the current node to [newParent].
+  /// This is needed so that trees that don't store text as nodes move the
+  /// text in the correct way.
   void reparentChildren(Node newParent) {
     newParent.nodes.addAll(nodes);
     nodes.clear();
   }
 
-  /** *Deprecated* use [querySelector] instead. */
+  /// *Deprecated* use [querySelector] instead.
   @deprecated
   Element query(String selectors) => querySelector(selectors);
 
-  /** *Deprecated* use [querySelectorAll] instead. */
+  /// *Deprecated* use [querySelectorAll] instead.
   @deprecated
   List<Element> queryAll(String selectors) => querySelectorAll(selectors);
 
-  /**
-   * Seaches for the first descendant node matching the given selectors, using a
-   * preorder traversal. NOTE: right now, this supports only a single type
-   * selectors, e.g. `node.query('div')`.
-   */
+  /// Seaches for the first descendant node matching the given selectors, using a
+  /// preorder traversal. NOTE: right now, this supports only a single type
+  /// selectors, e.g. `node.query('div')`.
 
   Element querySelector(String selectors) =>
       _queryType(_typeSelector(selectors));
 
-  /**
-   * Returns all descendant nodes matching the given selectors, using a
-   * preorder traversal. NOTE: right now, this supports only a single type
-   * selectors, e.g. `node.queryAll('div')`.
-   */
+  /// Returns all descendant nodes matching the given selectors, using a
+  /// preorder traversal. NOTE: right now, this supports only a single type
+  /// selectors, e.g. `node.queryAll('div')`.
   List<Element> querySelectorAll(String selectors) {
     var results = new List<Element>();
     _queryAllType(_typeSelector(selectors), results);
     return results;
   }
 
   bool hasChildNodes() => !nodes.isEmpty;
 
   bool contains(Node node) => nodes.contains(node);
 
   String _typeSelector(String selectors) {
     selectors = selectors.trim();
     if (!_isTypeSelector(selectors)) {
       throw new UnimplementedError('only type selectors are implemented');
     }
     return selectors;
   }
 
-  /**
-   * Checks if this is a type selector.
-   * See <http://www.w3.org/TR/CSS2/grammar.html>.
-   * Note: this doesn't support '*', the universal selector, non-ascii chars or
-   * escape chars.
-   */
+  /// Checks if this is a type selector.
+  /// See <http://www.w3.org/TR/CSS2/grammar.html>.
+  /// Note: this doesn't support '*', the universal selector, non-ascii chars or
+  /// escape chars.
   bool _isTypeSelector(String selector) {
     // Parser:
 
     // element_name
     //   : IDENT | '*'
     //   ;
 
     // Lexer:
 
     // nmstart   [_a-z]|{nonascii}|{escape}
@@ skipping 34 matching lines @@
   }
 
   void _queryAllType(String tag, List<Element> results) {
     for (var node in nodes) {
       if (node is! Element) continue;
       if (node.tagName == tag) results.add(node);
       node._queryAllType(tag, results);
     }
   }
 
-  /** Initialize [attributeSpans] using [sourceSpan]. */
+  /// Initialize [attributeSpans] using [sourceSpan].
   void _ensureAttributeSpans() {
     if (_attributeSpans != null) return;
 
     _attributeSpans = new LinkedHashMap<dynamic, FileSpan>();
     _attributeValueSpans = new LinkedHashMap<dynamic, FileSpan>();
 
     if (sourceSpan == null) return;
 
     var tokenizer = new HtmlTokenizer(sourceSpan.text, generateSpans: true,
         attributeSpans: true);
@@ skipping 73 matching lines @@
   }
 
   DocumentType clone() => new DocumentType(tagName, publicId, systemId);
 }
 
 class Text extends Node {
   String data;
 
   Text(this.data) : super(null);
 
-  /** *Deprecated* use [data]. */
+  /// *Deprecated* use [data].
   @deprecated String get value => data;
   @deprecated set value(String x) { data = x; }
 
   int get nodeType => Node.TEXT_NODE;
 
   String toString() => '"$data"';
 
   void _addOuterHtml(StringBuffer str) {
     // Don't escape text for certain elements, notably <script>.
     if (rcdataElements.contains(parent.tagName) ||
@@ skipping 260 matching lines @@
     super.retainWhere(test);
   }
 
   void insertAll(int index, List<Node> nodes) {
     for (var node in nodes) _setParent(node);
     super.insertAll(index, nodes);
   }
 }
 
 
-/**
- * An indexable collection of a node's descendants in the document tree,
- * filtered so that only elements are in the collection.
- */
+/// An indexable collection of a node's descendants in the document tree,
+/// filtered so that only elements are in the collection.
 // TODO(jmesserly): this was copied from dart:html
 // TODO(jmesserly): "implements List<Element>" is a workaround for analyzer bug.
 class FilteredElementList extends IterableBase<Element> with ListMixin<Element>
     implements List<Element> {
 
   final Node _node;
   final List<Node> _childNodes;
 
-  /**
-   * Creates a collection of the elements that descend from a node.
-   *
-   * Example usage:
-   *
-   *     var filteredElements = new FilteredElementList(query("#container"));
-   *     // filteredElements is [a, b, c].
-   */
+  /// Creates a collection of the elements that descend from a node.
+  ///
+  /// Example usage:
+  ///
+  ///     var filteredElements = new FilteredElementList(query("#container"));
+  ///     // filteredElements is [a, b, c].
   FilteredElementList(Node node): _childNodes = node.nodes, _node = node;
 
   // We can't memoize this, since it's possible that children will be messed
   // with externally to this class.
   //
   // TODO(nweiz): we don't always need to create a new list. For example
   // forEach, every, any, ... could directly work on the _childNodes.
   List<Element> get _filtered =>
     new List<Element>.from(_childNodes.where((n) => n is Element));
 
@@ skipping 164 matching lines @@
 
 class _ConcatTextVisitor extends TreeVisitor {
   final _str = new StringBuffer();
 
   String toString() => _str.toString();
 
   visitText(Text node) {
     _str.write(node.data);
   }
 }