Adding docs to Element.

sdk/lib/html/templates/html/impl/impl_Element.darttemplate

Index: sdk/lib/html/templates/html/impl/impl_Element.darttemplate
diff --git a/sdk/lib/html/templates/html/impl/impl_Element.darttemplate b/sdk/lib/html/templates/html/impl/impl_Element.darttemplate
index b253d2d3602e40f86970000e34b563a88f3d1a5b..3d305ea0885566ee575ee2439797c920c6ff726f 100644
--- a/sdk/lib/html/templates/html/impl/impl_Element.darttemplate
+++ b/sdk/lib/html/templates/html/impl/impl_Element.darttemplate
@@ -348,17 +348,54 @@ class _ElementCssClassSet extends CssClassSet {
   }
 }
 
-/// @domName $DOMNAME
+/**
+ * An abstract class which all HTML elements extend.

[Andrei Mouravski, 2012/12/12 18:56:17]

Either put a comma before which: "... class, which..."
or change which to that: "... class that..."

[blois, 2012/12/12 19:46:29]

Done.

+ */
 abstract class $CLASSNAME$EXTENDS$IMPLEMENTS$NATIVESPEC {
 
+  /**
+   * Creates an HTML element from a valid fragment of HTML.
+   *
+   * 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].
+   *
+   *    var element = new Element.html('<div class="foo">content</div>');
+   */
   factory $CLASSNAME.html(String html) =>
       _$(CLASSNAME)FactoryProvider.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].

[Andrei Mouravski, 2012/12/12 18:56:17]

New line here.

[blois, 2012/12/12 19:46:29]

Done.

+   *     var divElement = new Element.tag('div');
+   *     print(divElement is DivElement); // 'true'
+   *     var myElement = new Element.tag('unknownTag');
+   *     print(myElement is UnknownElement); // 'true'

[Andrei Mouravski, 2012/12/12 18:56:17]

New line here.

[blois, 2012/12/12 19:46:29]

Done.

+   * For standard elements it is more preferable to use the type constructors:
+   *     var element = new DivElement();
+   */
   factory $CLASSNAME.tag(String tag) =>
       _$(CLASSNAME)FactoryProvider.createElement_tag(tag);
 
   /**
-   * @domName Element.hasAttribute, Element.getAttribute, Element.setAttribute,
-   *   Element.removeAttribute
+   * All attributes on this element.
+   *
+   * Any modifications to the attribute map will automatically be applied to
+   * this element.
+   *
+   * This only includes attributes which are not in a namespace
+   * (such as xlink:href), additional attributes can be accessed via

[Andrei Mouravski, 2012/12/12 18:56:17]

Either code font backticks on xlink:href or quotes around it. Not sure which is
more appropriate.

[blois, 2012/12/12 19:46:29]

Done.

+   * [getNamespacedAttributes].
    */
   Map<String, String> get attributes => new _ElementAttributeMap(this);
 
@@ -392,8 +429,15 @@ abstract class $CLASSNAME$EXTENDS$IMPLEMENTS$NATIVESPEC {
   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.

[Andrei Mouravski, 2012/12/12 18:56:17]

New line before code block.

[blois, 2012/12/12 19:46:29]

Done.

+   *     var item = new DivElement();
+   *     item.text = 'Something';
+   *     document.body.children.add(item) // Item is now displayed on the page.
+   *     for (var element in document.body.children) {
+   *       element.style.background = 'red'; // Turns every child of body red.
+   *     }
    */
   List<Element> get children => new _ChildrenElementList._wrap(this);
 
@@ -405,12 +449,43 @@ abstract class $CLASSNAME$EXTENDS$IMPLEMENTS$NATIVESPEC {
     children.addAll(copy);
   }
 
+  /**
+   * Finds the first descendant element of this element that matches the
+   * specified group of selectors.
+   *
+   * [selectors] should be a string using CSS selector syntax.
+   * Get the first descendant with the class 'classname':

[Andrei Mouravski, 2012/12/12 18:56:17]

Maybe make all of this a code block with "Get the" being comments? Your choice.

Either way, newline before "Get the first..."

[blois, 2012/12/12 19:46:29]

Done.

+   *     var element = element.query('.className');
+   * Get the element with id 'id':
+   *     var element = element.query('#id');
+   * Get the first descendant [ImageElement]:
+   *     var img = element.query('img');
+   *
+   * See also:
+   *
+   * * [CSS Selectors](http://docs.webplatform.org/wiki/css/selectors)
+   */
   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.

[Andrei Mouravski, 2012/12/12 18:56:17]

Newline.

[blois, 2012/12/12 19:46:29]

Done.

+   *     element.classes.add('selected');
+   *     element.classes.toggle('isOnline');
+   *     element.classes.remove('selected');
+   */
   CssClassSet get classes => new _ElementCssClassSet(this);
 
   void set classes(Collection<String> value) {
@@ -419,6 +494,25 @@ abstract class $CLASSNAME$EXTENDS$IMPLEMENTS$NATIVESPEC {
     classSet.addAll(value);
   }
 
+  /**
+   * Allows access to all custom data attributes (data-*) set on this element.
+   *
+   * The keys for the map must follow these rules:
+   *
+   * * The name must not begin with `xml`.

[Andrei Mouravski, 2012/12/12 18:56:17]

I think quotes are better for talking about strings instead of codefont.

[blois, 2012/12/12 19:46:29]

Done.

+   * * The name cannot contain a semi-colon (`;`).
+   * * The name cannot contain any capital letters.
+   *
+   * Any keys from markup will be converted to camel-cased keys in the map.

[Andrei Mouravski, 2012/12/12 18:56:17]

New line before "For example."

[blois, 2012/12/12 19:46:29]

Done.

+   * For example, HTML specified as:

[Andrei Mouravski, 2012/12/12 18:56:17]

Newlines before and after code blocks.

[blois, 2012/12/12 19:46:29]

Done.

+   *     <div data-my-random-value='value'></div>div
+   * Would be accessed in Dart as:
+   *     var value = element.dataAttributes['myRandomValue'];
+   *
+   * See also:
+   *
+   * * [Custom data attributes](http://www.w3.org/TR/html5/global-attributes.html#custom-data-attribute)
+   */
   Map<String, String> get dataAttributes =>
     new _DataAttributeMap(attributes);
 
@@ -432,19 +526,39 @@ abstract class $CLASSNAME$EXTENDS$IMPLEMENTS$NATIVESPEC {
 
   /**
    * 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 */
+  /**
+   * The set of all CSS values applied to this element, including inherited
+   * and default values.
+   *
+   * The computedStyle contains the values which are inherited from other
+   * sources, such as parent elements or stylesheets. This differs from the
+   * [style] property which contains the values specified directly on this
+   * element,
+   *
+   * See also:
+   *
+   * * [CSS Inheritance and Cascade](http://docs.webplatform.org/wiki/tutorials/inheritance_and_cascade)
+   */
   Future<CssStyleDeclaration> get computedStyle {
      // TODO(jacobr): last param should be null, see b/5045788
      return getComputedStyle('');
   }
 
-  /** @domName Window.getComputedStyle */
+  /**
+   * This returns the computed styles for pseudo-elements such as

[Andrei Mouravski, 2012/12/12 18:56:17]

I think commas should not be code font.

[blois, 2012/12/12 19:46:29]

Done.

+   * `::after, ::before, ::marker, ::line-marker`.
+   *
+   * See also:
+   *
+   * * [Pseudo-elements](http://docs.webplatform.org/wiki/css/selectors/pseudo-elements)
+   */
   Future<CssStyleDeclaration> getComputedStyle(String pseudoElement) {
     return _createMeasurementFuture(
         () => window.$dom_getComputedStyle(this, pseudoElement),
@@ -509,7 +623,20 @@ $else
 $endif
 
 $if DART2JS
-  /** @domName Element.insertAdjacentText */
+  /**
+   * Creates a text node and inserts it into the DOM at the specified location.
+   *
+   * The [where] parameter indicates where to insert [text]:
+   *
+   * * `beforeBegin` Immediately before this element.

[Andrei Mouravski, 2012/12/12 18:56:17]

Quotes instead of code font, I think is better for Strings.

[blois, 2012/12/12 19:46:29]

Done.

+   * * `afterBegin` As the first child of this element.
+   * * `beforeEnd` As the last child of this element.
+   * * `afterEnd` Immediately after this element.
+   *
+   * See also:
+   *
+   * * [insertAdjacentHtml]
+   */
   void insertAdjacentText(String where, String text) {
     if (JS('bool', '!!#.insertAdjacentText', this)) {
       _insertAdjacentText(where, text);
@@ -521,7 +648,23 @@ $if DART2JS
   @JSName('insertAdjacentText')
   void _insertAdjacentText(String where, String text) native;
 
-  /** @domName Element.insertAdjacentHTML */
+  /**
+   * Parses text as an HTML fragment and inserts it into the DOM at the
+   * specified location.
+   *
+   * The [where] parameter indicates where to insert the HTML fragment:
+   *
+   * * `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.
+   *
+   *     var html = '<div class="something">content</div>';
+   *     // Inserts as the first child
+   *     document.body.insertAdjacentHtml('afterBegin', html);
+   *     var createdElement = document.body.children[0];
+   *     print(createdElement.classes[0]); // Prints 'something'
+   */
   void insertAdjacentHtml(String where, String text) {
     if (JS('bool', '!!#.insertAdjacentHtml', this)) {
       _insertAdjacentHtml(where, text);
@@ -533,7 +676,20 @@ $if DART2JS
   @JSName('insertAdjacentHTML')
   void _insertAdjacentHTML(String where, String text) native;
 
-  /** @domName Element.insertAdjacentHTML */
+  /**
+   * Inserts [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.
+   *
+   * See also:
+   *
+   * * [insertAdjacentHtml]
+   */
   Element insertAdjacentElement(String where, Element element) {
     if (JS('bool', '!!#.insertAdjacentElement', this)) {
       _insertAdjacentElement(where, element);