Adding docs to Element.

sdk/lib/html/dart2js/html_dart2js.dart

 library html;
 
 import 'dart:isolate';
 import 'dart:json';
 import 'dart:svg' as svg;
 // Copyright (c) 2012, 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.
 
 // DO NOT EDIT
@@ skipping 7318 matching lines @@
     }
     return s;
   }
 
   void writeClasses(Set<String> s) {
     List list = new List.from(s);
     _element.$dom_className = Strings.join(list, ' ');
   }
 }
 
+/**
+ * The base class of all components for an HTML document.
+ */
 abstract class Element extends Node implements ElementTraversal native "*Element" {
 
+  /**
+   * Creates an HTML Element from a valid fragment of HTML.

[Kathy Walrath, 2012/11/27 21:53:42]

Add a blank line after. (Do this globally.)

Also, Element -> element (or maybe "HTML Element" -> "element" or "Element")
Otherwise, it seems like there might be other kinds of Elements.

[blois, 2012/12/12 01:03:44]

Done.

+   * The [html] fragment must represent valid HTML with a single element root,
+   * which will be parsed and returned.
+   *
+   * Important: the contents of [html] should not contain any user-supplied
+   * data. Without strict data validation it is impossible to prevent script
+   * injection exploits.
+   *
+   * It is instead recommended that elements be constructed via [Element.tag]
+   * and text be added via [text].
+   */
   factory Element.html(String html) =>
       _ElementFactoryProvider.createElement_html(html);
+
+  /**
+   * Creates the HTML element specified by the tag name.
+   * This is similar to document.createElement.
+   * [tag] should be a valid HTML tag name. If [tag] is an unknown tag then
+   * this will create an [UnknownElement].
+   *     var element = new Element.tag('div');
+   * For standard elements it is more preferable to use the type constructors:
+   *     var element = new DivElement();
+   */
   factory Element.tag(String tag) =>
       _ElementFactoryProvider.createElement_tag(tag);
 
   /**
-   * @domName Element.hasAttribute, Element.getAttribute, Element.setAttribute,
-   *   Element.removeAttribute
+   * Provides access to all attributes on this element.
+   * This only includes attributes in the default namespace, additional
+   * attributes can be accessed via [getNamespacedAttributes].
+   * Any modifications to the map will automatically be applied to this
+   * element.
    */
   Map<String, String> get attributes => new _ElementAttributeMap(this);
 
   void set attributes(Map<String, String> value) {
     Map<String, String> attributes = this.attributes;
     attributes.clear();
     for (String key in value.keys) {
       attributes[key] = value[key];
     }
   }
 
   /**
    * Deprecated, use innerHtml instead.
    */
   String get innerHTML => this.innerHtml;
   void set innerHTML(String value) {
     this.innerHtml = value;
   }
 
   void set elements(Collection<Element> value) {
     this.children = value;
   }
 
   /**
    * Deprecated, use [children] instead.
    */
   List<Element> get elements => this.children;
 
   /**
-   * @domName childElementCount, firstElementChild, lastElementChild,
-   *   children, Node.nodes.add
+   * List of the direct children of this element.
+   * This collection can be used to add and remove elements from the document.
    */
   List<Element> get children => new _ChildrenElementList._wrap(this);
 
   void set children(Collection<Element> value) {
     // Copy list first since we don't want liveness during iteration.
     List copy = new List.from(value);
     var children = this.children;
     children.clear();
     children.addAll(copy);
   }
 
+  /**
+   * Finds the first descendent element of this element that matches the
+   * specified group of selectors.
+   * [selectors] should be a string using CSS selector syntax.
+   *     var element = element.query('.className');
+   *     var element = element.query('#id');
+   */
   Element query(String selectors) => $dom_querySelector(selectors);
 
+  /**
+   * Finds all descendent elements of this element that match the specified
+   * group of selectors.
+   * [selectors] should be a string using CSS selector syntax.
+   *     var items = element.query('.itemClassName');
+   */
   List<Element> queryAll(String selectors) =>
     new _FrozenElementList._wrap($dom_querySelectorAll(selectors));
 
-  /** @domName className, classList */
+  /**
+   * The set of CSS classes applied to this element.
+   * This set makes it easy to add, remove or toggle the classes applied to
+   * this element.
+   *     element.classes.add('selected');
+   *     element.classes.toggle('isOnline');
+   *     element.classes.remove('selected');
+   */
   CssClassSet get classes => new _ElementCssClassSet(this);
 
   void set classes(Collection<String> value) {
     CssClassSet classSet = classes;
     classSet.clear();
     classSet.addAll(value);
   }
 
+  /**
+   * Allows access to all custom data attributes (data-*) set on this element.
+   * The keys for the map must follow these rules:

[Kathy Walrath, 2012/11/27 21:53:42]

Add blank lines before and after this line.
(Bulleted lists must be preceded by a blank line, sadly.)

[blois, 2012/12/12 01:03:44]

Done.

+   * * The name must not begin with `xml`.
+   * * The name cannot contain a semi-colon (`;`).
+   * * The name cannot contain any capitol letters.
+   *
+   * Any keys from markup will be converted to camel-cased keys in the map
+   * This means that a key of 'camel-cased-name' would be converted to
+   * 'camelCasedName'.
+   */
   Map<String, String> get dataAttributes =>
     new _DataAttributeMap(attributes);
 
   void set dataAttributes(Map<String, String> value) {
     final dataAttributes = this.dataAttributes;
     dataAttributes.clear();
     for (String key in value.keys) {
       dataAttributes[key] = value[key];
     }
   }
 
   /**
    * Gets a map for manipulating the attributes of a particular namespace.
    * This is primarily useful for SVG attributes such as xref:link.
    */
   Map<String, String> getNamespacedAttributes(String namespace) {
     return new _NamespacedAttributeMap(this, namespace);
   }
 
-  /** @domName Window.getComputedStyle */
+  /**
+   * Gets the final set of all CSS values applied to this element, including
+   * inherited and default values.
+   * As opposed to the [style] property which contains the values specified
+   * directly on this element, computedStyle contains the values which are
+   * inherited from other sources, such as parent elements or stylesheets.
+   */
   Future<CSSStyleDeclaration> get computedStyle {
      // TODO(jacobr): last param should be null, see b/5045788
      return getComputedStyle('');
   }
 
-  /** @domName Window.getComputedStyle */
+  /**
+   * Gets the computed style of a pseudoElement of this element.
+   * Similar to [computedStyle] but this targets pseudo-elements such as
+   * `::after, ::before, ::marker, ::line-marker`.
+   */
   Future<CSSStyleDeclaration> getComputedStyle(String pseudoElement) {
     return _createMeasurementFuture(
         () => window.$dom_getComputedStyle(this, pseudoElement),
         new Completer<CSSStyleDeclaration>());
   }
 
   /**
    * Adds the specified text as a text node after the last child of this.
    */
   void addText(String text) {
@@ skipping 17 matching lines @@
    * deprecated and will simply return this [Element] object.
    *
    * [wc]: http://dvcs.w3.org/hg/webcomponents/raw-file/tip/explainer/index.html
    * [x-tags]: http://x-tags.org/
    */
   @Creates('Null')  // Set from Dart code; does not instantiate a native type.
   var xtag;
 
   // TODO(vsm): Implement noSuchMethod or similar for dart2js.
 
-  /** @domName Element.insertAdjacentText */
+  /**
+   * Creates a text node and inserts it into the DOM at the specified location.
+   * The [where] parameter indicates:
+   * * `beforeBegin` Immediately before this element.
+   * * `afterBegin` As the first child of this element.
+   * * `beforeEnd` As the last child of this element.
+   * * `afterEnd` Immediately after this element.
+   */
   void insertAdjacentText(String where, String text) {
     if (JS('bool', '!!#.insertAdjacentText', this)) {
       _insertAdjacentText(where, text);
     } else {
       _insertAdjacentNode(where, new Text(text));
     }
   }
 
   void _insertAdjacentText(String where, String text)
       native 'insertAdjacentText';
 
-  /** @domName Element.insertAdjacentHTML */
+  /**
+   * Parses [text] as an HTML fragment and inserts it into the DOM at the
+   * specified location.
+   * The [where] parameter indicates:

[Kathy Walrath, 2012/11/27 21:53:42]

indicates -> indicates where to insert the HTML fragment:

(plus see below for other suggestions)

[blois, 2012/12/12 01:03:44]

Done.

+   * * `beforeBegin` Immediately before this element.
+   * * `afterBegin` As the first child of this element.
+   * * `beforeEnd` As the last child of this element.
+   * * `afterEnd` Immediately after this element.
+   */
   void insertAdjacentHtml(String where, String text) {
     if (JS('bool', '!!#.insertAdjacentHtml', this)) {
       _insertAdjacentHtml(where, text);
     } else {
       _insertAdjacentNode(where, new DocumentFragment.html(text));
     }
   }
 
   void _insertAdjacentHtml(String where, String text)
       native 'insertAdjacentHTML';
 
-  /** @domName Element.insertAdjacentHTML */
+  /**
+   * Inserts [element] into the DOM at the specified location.
+   * The [where] parameter indicates:
+   * * `beforeBegin` Immediately before this element.
+   * * `afterBegin` As the first child of this element.
+   * * `beforeEnd` As the last child of this element.
+   * * `afterEnd` Immediately after this element.
+   */

[Kathy Walrath, 2012/11/27 21:53:42]

You need a blank line before the bulleted list. How about doing something like
this (here and in similar places):

  /**
   * Inserts an element into the DOM at the specified location.
   * 
   * The [where] parameter indicates where to insert [element]:
   * 
   * * "beforeBegin": Immediately before this element.
   * * "afterBegin": As the first child of this element.
   * * "beforeEnd": As the last child of this element.
   * * "afterEnd": Immediately after this element.
   */

[blois, 2012/12/12 01:03:44]

Done.

   Element insertAdjacentElement(String where, Element element) {
     if (JS('bool', '!!#.insertAdjacentElement', this)) {
       _insertAdjacentElement(where, element);
     } else {
       _insertAdjacentNode(where, element);
     }
     return element;
   }
 
   void _insertAdjacentElement(String where, Element element)
@@ skipping 17562 matching lines @@
     if (length < 0) throw new ArgumentError('length');
     if (start < 0) throw new RangeError.value(start);
     int end = start + length;
     if (end > a.length) throw new RangeError.value(end);
     for (int i = start; i < end; i++) {
       accumulator.add(a[i]);
     }
     return accumulator;
   }
 }