Even more docs, filling in many of the gaps.

Even more docs, filling in many of the gaps.

Committed: https://code.google.com/p/dart/source/detail?r=29993

[Andrei Mouravski, 2013-11-06 20:35:00]

Submitting TBR.

[Andrei Mouravski, 2013-11-06 20:39:37]

Committed patchset #4 manually as r29993 (presubmit successful).

[Kathy Walrath, 2013-11-06 23:13:48]

lgtm, but I have some questions about conventions.

https://codereview.chromium.org/62703002/diff/90001/sdk/lib/html/dart2js/html...
File sdk/lib/html/dart2js/html_dart2js.dart (right):

https://codereview.chromium.org/62703002/diff/90001/sdk/lib/html/dart2js/html...
sdk/lib/html/dart2js/html_dart2js.dart:14458: +   * ## Other resources
I'm not sure that we should take up so much space. "## Other resources" makes
sense in a class/library description, but having many occurrences of it on a
page might just annoy people, especially in cases where there's only one link.

An alternative is to just put the links into a sentence. E.g.:

For more information, see the XMLHttpRequest.timeout documentation [from MDN]
and [from W3C].

Or just go back to "See also:" optionally with a bulleted list after it.

(This comment applies globally.)

https://codereview.chromium.org/62703002/diff/90001/sdk/lib/html/dart2js/html...
sdk/lib/html/dart2js/html_dart2js.dart:19460: +   * A list of this node's
children.
A list -> A read-only list

?

https://codereview.chromium.org/62703002/diff/90001/sdk/lib/html/dart2js/html...
sdk/lib/html/dart2js/html_dart2js.dart:19475: +   * The first child of this
node.
Mention that it's read only? E.g.:

The first child of this node. (read only)

https://codereview.chromium.org/62703002/diff/90001/sdk/lib/html/dart2js/html...
sdk/lib/html/dart2js/html_dart2js.dart:19488: +   * The last child of this node.
Mention that it's read only?

https://codereview.chromium.org/62703002/diff/90001/sdk/lib/html/dart2js/html...
sdk/lib/html/dart2js/html_dart2js.dart:19512: +   * The next sibling node.
read only?

https://codereview.chromium.org/62703002/diff/90001/sdk/lib/html/dart2js/html...
sdk/lib/html/dart2js/html_dart2js.dart:19525: +   * The name of this node.
read only?

https://codereview.chromium.org/62703002/diff/90001/sdk/lib/html/dart2js/html...
sdk/lib/html/dart2js/html_dart2js.dart:19527: +   * This varies by this node's
[nodeType].
What does "This" mean here? Maybe:

The value assigned to this property depends on the node type.

https://codereview.chromium.org/62703002/diff/90001/sdk/lib/html/dart2js/html...
sdk/lib/html/dart2js/html_dart2js.dart:19541: +   * The type of node.
read only

https://codereview.chromium.org/62703002/diff/90001/sdk/lib/html/dart2js/html...
sdk/lib/html/dart2js/html_dart2js.dart:19568: +   * The value of this node.
read only

https://codereview.chromium.org/62703002/diff/90001/sdk/lib/html/dart2js/html...
sdk/lib/html/dart2js/html_dart2js.dart:19584: +   * The document this node
belongs to.
read only

https://codereview.chromium.org/62703002/diff/90001/sdk/lib/html/dart2js/html...
sdk/lib/html/dart2js/html_dart2js.dart:19586: +   * Returns `null` if this node
does not belong to any document.
Returns -> The value is

https://codereview.chromium.org/62703002/diff/90001/sdk/lib/html/dart2js/html...
sdk/lib/html/dart2js/html_dart2js.dart:19600: +   * The parent element of this
node.
read only

(I'm going to stop marking these... just search for "final")

https://codereview.chromium.org/62703002/diff/90001/sdk/lib/html/dart2js/html...
sdk/lib/html/dart2js/html_dart2js.dart:19602: +   * Returns `null` if this node
either does not have a parent or its parent is
Returns -> The value is

(I'm going to stop marking these... just search for "Returns" on fields.)