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 e6f45b7831264a8053e8ec1ad3364eba7ebdb5af..4fba3c47ee01ae63a1b95e6578f4652303942cc7 100644
--- a/sdk/lib/html/templates/html/impl/impl_Element.darttemplate
+++ b/sdk/lib/html/templates/html/impl/impl_Element.darttemplate
@@ -326,16 +326,44 @@ class _ElementCssClassSet extends CssClassSet {
   }
 }
 
+/**
+ * The base class of all components for an HTML document.

[Andrei Mouravski, 2012/11/27 21:19:52]

"... all components of an ..." maybe?

[Andrei Mouravski, 2012/11/27 21:19:52]

Also, what is a "component" exactly?

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

Done.

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

Reworded some.

+ */
 abstract class $CLASSNAME$EXTENDS$IMPLEMENTS$NATIVESPEC {
 
+  /**
+   * Creates an HTML Element from a valid fragment of HTML.

[Andrei Mouravski, 2012/11/27 21:19:52]

I think we've been doing it so the first sentence is its own paragraph.

[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].

[Andrei Mouravski, 2012/11/27 21:19:52]

Can you add sample code for how this method works?

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

Done.

+   */
   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.

[Andrei Mouravski, 2012/11/27 21:19:52]

"[document.createElement]" maybe?

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

Done.

+   * [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();

[Andrei Mouravski, 2012/11/27 21:19:52]

Maybe add:

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

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

Done.

+   */
   factory $CLASSNAME.tag(String tag) =>
       _$(CLASSNAME)FactoryProvider.createElement_tag(tag);
 
   /**
-   * @domName Element.hasAttribute, Element.getAttribute, Element.setAttribute,
-   *   Element.removeAttribute
+   * Provides access to all attributes on this element.

[Andrei Mouravski, 2012/11/27 21:19:52]

"Static/instance variable and getter/setter descriptions are noun phrases."

Should be:
"All attributes of this element."

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

Done.

+   * 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

[Andrei Mouravski, 2012/11/27 21:19:52]

Maybe "any modifications to the attribute map will ..."

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

Done.

+   * element.

[Andrei Mouravski, 2012/11/27 21:19:52]

Can you add details on what "default namespace" means?

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

Done.

    */
   Map<String, String> get attributes => new _ElementAttributeMap(this);
 
@@ -365,8 +393,8 @@ 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/11/27 21:19:52]

Can you add code samples for this method? It's a really important one.

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

Done.

    */
   List<Element> get children => new _ChildrenElementList._wrap(this);
 
@@ -378,12 +406,32 @@ abstract class $CLASSNAME$EXTENDS$IMPLEMENTS$NATIVESPEC {
     children.addAll(copy);
   }
 
+  /**
+   * Finds the first descendent element of this element that matches the
+   * specified group of selectors.

[Andrei Mouravski, 2012/11/27 21:19:52]

This is another really important method that could use more details.
Specifically, code samples for this would be handy, and especially useful would
be a "See also:" to the CSS selectors syntax.

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

Done.

+   * [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) {
@@ -392,6 +440,17 @@ 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:

[Andrei Mouravski, 2012/11/27 21:19:52]

With all of these rules, it'd be nice to have a "See also:" as to the source of
the rules.

[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.

[Andrei Mouravski, 2012/11/27 21:19:52]

"capital"

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

Done.

+   *
+   * Any keys from markup will be converted to camel-cased keys in the map

[Andrei Mouravski, 2012/11/27 21:19:52]

I have no idea what this means.
"from markup"?
Who converts what where?

Code samples would be helpful here.

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

Done.

+   * This means that a key of 'camel-cased-name' would be converted to
+   * 'camelCasedName'.
+   */
   Map<String, String> get dataAttributes =>
     new _DataAttributeMap(attributes);
 
@@ -411,13 +470,23 @@ abstract class $CLASSNAME$EXTENDS$IMPLEMENTS$NATIVESPEC {
     return new _NamespacedAttributeMap(this, namespace);
   }
 
-  /** @domName Window.getComputedStyle */
+  /**
+   * Gets the final set of all CSS values applied to this element, including

[Andrei Mouravski, 2012/11/27 21:19:52]

Noun phrase.

[Andrei Mouravski, 2012/11/27 21:19:52]

I think "final set" is weird. Final is a keyword, and means something different.

I think better would be:
"The set of all CSS styles applied to this element, including inherited and
default styles."

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

Done.

+   * inherited and default values.
+   * As opposed to the [style] property which contains the values specified

[Andrei Mouravski, 2012/11/27 21:19:52]

Reverse these clauses to focus on computedStyle.

"Computed style contains..., as opposed to [style]..."

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

Done.

+   * directly on this element, computedStyle contains the values which are
+   * inherited from other sources, such as parent elements or stylesheets.

[Andrei Mouravski, 2012/11/27 21:19:52]

Maybe a see also on inherited styles?

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

Done.

+   */
   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

[Andrei Mouravski, 2012/11/27 21:19:52]

I think it'd be better to say something like "This returns the computed styles
for pseudo-elements such as..."

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

Done.

+   * `::after, ::before, ::marker, ::line-marker`.

[Andrei Mouravski, 2012/11/27 21:19:52]

See also on pseudo elements maybe?

[Andrei Mouravski, 2012/11/27 21:19:52]

Maybe note that all pseudo elements begin with '::' if they do, or otherwise.

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

They normally do, but there's essentially a fixed list. I'd prefer to rely on
the linked documentation for the supported values.

+   */
   Future<CSSStyleDeclaration> getComputedStyle(String pseudoElement) {
     return _createMeasurementFuture(
         () => window.$dom_getComputedStyle(this, pseudoElement),
@@ -475,7 +544,14 @@ $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:

[Andrei Mouravski, 2012/11/27 21:19:52]

I think this is a clunky way of expressing the enumeration.
Maybe ask Kathy as the best way to do this, as I imagine we're going to need to
do this elsewhere.

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

Maybe I should open a bug to add enum support to Dart? Would make it clearer :)

+   * * `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.

[Andrei Mouravski, 2012/11/27 21:19:52]

Maybe some sample code for this or more details? Does it show up in children for
example?

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

Done.

+   */
   void insertAdjacentText(String where, String text) {
     if (JS('bool', '!!#.insertAdjacentText', this)) {
       _insertAdjacentText(where, text);
@@ -487,7 +563,15 @@ $if DART2JS
   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

[Andrei Mouravski, 2012/11/27 21:19:52]

No [] in the first sentence.

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

Done.

+   * 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 insertAdjacentHtml(String where, String text) {
     if (JS('bool', '!!#.insertAdjacentHtml', this)) {
       _insertAdjacentHtml(where, text);
@@ -499,7 +583,14 @@ $if DART2JS
   void _insertAdjacentHtml(String where, String text)
       native 'insertAdjacentHTML';
 
-  /** @domName Element.insertAdjacentHTML */
+  /**
+   * Inserts [element] into the DOM at the specified location.
+   * The [where] parameter indicates:

[Andrei Mouravski, 2012/11/27 21:19:52]

Maybe make the enum as a class with private constructor and fields so that we
have instances of that class instead of "String"

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

http://code.google.com/p/dart/issues/detail?id=7329

+   * * `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.
+   */
   Element insertAdjacentElement(String where, Element element) {
     if (JS('bool', '!!#.insertAdjacentElement', this)) {
       _insertAdjacentElement(where, element);