Document the document class.

Document the document class.


BUG=

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

[Kathy Walrath, 2012-11-30 01:29:25]

yay, docs!

https://codereview.chromium.org/11316258/diff/1/sdk/lib/html/templates/html/i...
File sdk/lib/html/templates/html/impl/impl_Document.darttemplate (right):

https://codereview.chromium.org/11316258/diff/1/sdk/lib/html/templates/html/i...
sdk/lib/html/templates/html/impl/impl_Document.darttemplate:9: * The base class
for all documents.
Insert a blank line after this.

(applies globally: the first "sentence" -- really a sentence fragment but
whatever -- should be a paragraph)

https://codereview.chromium.org/11316258/diff/1/sdk/lib/html/templates/html/i...
sdk/lib/html/templates/html/impl/impl_Document.darttemplate:10: * Each web page
loaded in the browser has its own document object which is

document -> Document

which -> , which

https://codereview.chromium.org/11316258/diff/1/sdk/lib/html/templates/html/i...
sdk/lib/html/templates/html/impl/impl_Document.darttemplate:11: * typically an
[HtmlDocument].
Add a paragraph that links to the Dart tutorial. Maybe:

 * If you aren't comfortable with DOM concepts, see the Dart tutorial
 * [Target 2: Connect Dart &
HTML](http://www.dartlang.org/docs/tutorials/connect-dart-html/).
 */

https://codereview.chromium.org/11316258/diff/1/sdk/lib/html/templates/html/i...
sdk/lib/html/templates/html/impl/impl_Document.darttemplate:19: * Finds the
first descendent element of this document that matches the
descendent -> descendant (globally)

But maybe we could be more precise here about what "first" and "descendant"
mean.

https://codereview.chromium.org/11316258/diff/1/sdk/lib/html/templates/html/i...
sdk/lib/html/templates/html/impl/impl_Document.darttemplate:22: *     var
element = document.query('.className');
Explain when you would use Document.query() instead of the top-level query()
function, and link to the top-level query() function.

Also, maybe use different varnames (so this is more testable / easier to run)

element1 = ...
element2 = ...

Add a link to some good CSS selector doc. Maybe:

For details about CSS selector syntax, see the
[CSS selector specification](http://www.w3.org/TR/css3-selectors/).

https://codereview.chromium.org/11316258/diff/1/sdk/lib/html/templates/html/i...
sdk/lib/html/templates/html/impl/impl_Document.darttemplate:38: *     var items
= document.query('.itemClassName');
Again, explain when you would use Document.queryAll() instead of the top-level
queryAll() function, and link to the top-level queryAll() function.

Add a link to some good CSS selector doc, as above.

https://codereview.chromium.org/11316258/diff/1/sdk/lib/html/templates/html/i...
File sdk/lib/html/templates/html/impl/impl_EventTarget.darttemplate (right):

https://codereview.chromium.org/11316258/diff/1/sdk/lib/html/templates/html/i...
sdk/lib/html/templates/html/impl/impl_EventTarget.darttemplate:8: * Base class
that supports listening for and dispatching browser events.
Globally: add a blank line after the first sentence.

https://codereview.chromium.org/11316258/diff/1/sdk/lib/html/templates/html/i...
sdk/lib/html/templates/html/impl/impl_EventTarget.darttemplate:9: * Events can
either be accessed by string name using the indexed getter or by
parentheses around "using the indexed getter" would make this a little easier to
read.

An example (because what the heck does "indexed getter" mean?) would be even
nicer.

https://codereview.chromium.org/11316258/diff/1/sdk/lib/html/templates/html/i...
sdk/lib/html/templates/html/impl/impl_EventTarget.darttemplate:11: * possible
for better compile time type checks.

compile time -> compile-time

https://codereview.chromium.org/11316258/diff/1/sdk/lib/html/templates/html/i...
sdk/lib/html/templates/html/impl/impl_EventTarget.darttemplate:25: * Supports
adding, removing, and dispatch events for a specific event type.

dispatch -> dispatching

https://codereview.chromium.org/11316258/diff/1/sdk/lib/html/templates/html/i...
sdk/lib/html/templates/html/impl/impl_EventTarget.darttemplate:64: * Use the
[on] property to add, remove, and dispatch events rather than
long sentence!
adding parentheses around "rather than...]" would help readability.

https://codereview.chromium.org/11316258/diff/1/sdk/lib/html/templates/html/i...
sdk/lib/html/templates/html/impl/impl_EventTarget.darttemplate:65: *
[$dom_addEventListener, $dom_dispatchEvent, and $dom_removeEventListener]

put separate [...] around each name:

[$dom_addEventListener], [$dom_dispatchEvent], and [$dom_removeEventListener]

https://codereview.chromium.org/11316258/diff/1/sdk/lib/html/templates/html/i...
sdk/lib/html/templates/html/impl/impl_EventTarget.darttemplate:66: * for compile
time type checks and a more concise API.

compile time -> compile-time

(since this is an adjective clump before the noun. you wouldn't use a hyphen for
"at compile time".)

[jacob314, 2012-11-30 18:31:18]

PTAL
Btw, be sure to look at the comments only visible in

https://codereview.chromium.org/11316258/diff/1/sdk/lib/html/templates/html/i...
File sdk/lib/html/templates/html/impl/impl_Document.darttemplate (right):

https://codereview.chromium.org/11316258/diff/1/sdk/lib/html/templates/html/i...
sdk/lib/html/templates/html/impl/impl_Document.darttemplate:9: * The base class
for all documents.
On 2012/11/30 01:29:25, Kathy Walrath wrote:
> Insert a blank line after this.
> 
> (applies globally: the first "sentence" -- really a sentence fragment but
> whatever -- should be a paragraph)

Done.

https://codereview.chromium.org/11316258/diff/1/sdk/lib/html/templates/html/i...
sdk/lib/html/templates/html/impl/impl_Document.darttemplate:10: * Each web page
loaded in the browser has its own document object which is
On 2012/11/30 01:29:25, Kathy Walrath wrote:
> 
> document -> Document
> 
> which -> , which

Done.

https://codereview.chromium.org/11316258/diff/1/sdk/lib/html/templates/html/i...
sdk/lib/html/templates/html/impl/impl_Document.darttemplate:19: * Finds the
first descendent element of this document that matches the
On 2012/11/30 01:29:25, Kathy Walrath wrote:
> descendent -> descendant (globally)
> 
> But maybe we could be more precise here about what "first" and "descendant"
> mean.
Got ideas for some better wording? I fixed the spelling error.

https://codereview.chromium.org/11316258/diff/1/sdk/lib/html/templates/html/i...
sdk/lib/html/templates/html/impl/impl_Document.darttemplate:22: *     var
element = document.query('.className');
On 2012/11/30 01:29:25, Kathy Walrath wrote:
> Explain when you would use Document.query() instead of the top-level query()
> function, and link to the top-level query() function.
> 
> Also, maybe use different varnames (so this is more testable / easier to run)
> 
> element1 = ...
> element2 = ...
> 
> Add a link to some good CSS selector doc. Maybe:
> 
> For details about CSS selector syntax, see the
> [CSS selector specification](http://www.w3.org/TR/css3-selectors/).
> 

Done.

https://codereview.chromium.org/11316258/diff/1/sdk/lib/html/templates/html/i...
sdk/lib/html/templates/html/impl/impl_Document.darttemplate:38: *     var items
= document.query('.itemClassName');
On 2012/11/30 01:29:25, Kathy Walrath wrote:
> Again, explain when you would use Document.queryAll() instead of the top-level
> queryAll() function, and link to the top-level queryAll() function.
> 
> Add a link to some good CSS selector doc, as above.

Done.

https://codereview.chromium.org/11316258/diff/1/sdk/lib/html/templates/html/i...
File sdk/lib/html/templates/html/impl/impl_EventTarget.darttemplate (right):

https://codereview.chromium.org/11316258/diff/1/sdk/lib/html/templates/html/i...
sdk/lib/html/templates/html/impl/impl_EventTarget.darttemplate:8: * Base class
that supports listening for and dispatching browser events.
On 2012/11/30 01:29:25, Kathy Walrath wrote:
> Globally: add a blank line after the first sentence.

Done.

https://codereview.chromium.org/11316258/diff/1/sdk/lib/html/templates/html/i...
sdk/lib/html/templates/html/impl/impl_EventTarget.darttemplate:9: * Events can
either be accessed by string name using the indexed getter or by
On 2012/11/30 01:29:25, Kathy Walrath wrote:
> parentheses around "using the indexed getter" would make this a little easier
to
> read.
> 
> An example (because what the heck does "indexed getter" mean?) would be even
> nicer.

Done.

https://codereview.chromium.org/11316258/diff/1/sdk/lib/html/templates/html/i...
sdk/lib/html/templates/html/impl/impl_EventTarget.darttemplate:11: * possible
for better compile time type checks.
On 2012/11/30 01:29:25, Kathy Walrath wrote:
> 
> compile time -> compile-time

Done.

https://codereview.chromium.org/11316258/diff/1/sdk/lib/html/templates/html/i...
sdk/lib/html/templates/html/impl/impl_EventTarget.darttemplate:25: * Supports
adding, removing, and dispatch events for a specific event type.
On 2012/11/30 01:29:25, Kathy Walrath wrote:
> 
> dispatch -> dispatching

Done.

https://codereview.chromium.org/11316258/diff/1/sdk/lib/html/templates/html/i...
sdk/lib/html/templates/html/impl/impl_EventTarget.darttemplate:64: * Use the
[on] property to add, remove, and dispatch events rather than
On 2012/11/30 01:29:25, Kathy Walrath wrote:
> long sentence!
> adding parentheses around "rather than...]" would help readability.

Done.

https://codereview.chromium.org/11316258/diff/1/sdk/lib/html/templates/html/i...
sdk/lib/html/templates/html/impl/impl_EventTarget.darttemplate:65: *
[$dom_addEventListener, $dom_dispatchEvent, and $dom_removeEventListener]
On 2012/11/30 01:29:25, Kathy Walrath wrote:
> 
> put separate [...] around each name:
> 
> [$dom_addEventListener], [$dom_dispatchEvent], and [$dom_removeEventListener]

Done.

https://codereview.chromium.org/11316258/diff/1/sdk/lib/html/templates/html/i...
sdk/lib/html/templates/html/impl/impl_EventTarget.darttemplate:66: * for compile
time type checks and a more concise API.
On 2012/11/30 01:29:25, Kathy Walrath wrote:
> 
> compile time -> compile-time
> 
> (since this is an adjective clump before the noun. you wouldn't use a hyphen
for
> "at compile time".)

Done.

[Jacob, 2012-11-30 18:33:30]

last comment got cut off.
Only visible in sdk/lib/html/dart2js/html_dart2js.dart
These are the comments defined in the hard to read and review .json file.

[Kathy Walrath, 2012-11-30 18:50:14]

Looking good! Just a couple of nits.

https://codereview.chromium.org/11316258/diff/7/sdk/lib/html/dart2js/html_dar...
File sdk/lib/html/dart2js/html_dart2js.dart (right):

https://codereview.chromium.org/11316258/diff/7/sdk/lib/html/dart2js/html_dar...
sdk/lib/html/dart2js/html_dart2js.dart:6225: * Unless your webpage contains
multiple documents, the top level query
top level query -> top-level [query]

(top-level hyphenated because it's before the noun)

Could you please test how to link to the top-level query method? I'm not sure
whether [query] will link to it or to this one. Thanks!

https://codereview.chromium.org/11316258/diff/7/sdk/lib/html/dart2js/html_dar...
sdk/lib/html/dart2js/html_dart2js.dart:6226: * method behaves the same as this
method so you should use it instead to
method so you should use it -> method, so you can use it

https://codereview.chromium.org/11316258/diff/7/sdk/lib/html/dart2js/html_dar...
sdk/lib/html/dart2js/html_dart2js.dart:6249: * Unless your webpage contains
multiple documents, the top level queryAll
same comments as for query description above

https://codereview.chromium.org/11316258/diff/7/sdk/lib/html/dart2js/html_dar...
sdk/lib/html/dart2js/html_dart2js.dart:7905: *     events['mouseover'].add((e)
=> print("Mouse over!"))
Nice examples!

Add a ; to the end of each example.

[Jacob, 2012-11-30 20:59:50]

PTAL

https://codereview.chromium.org/11316258/diff/7/sdk/lib/html/dart2js/html_dar...
File sdk/lib/html/dart2js/html_dart2js.dart (right):

https://codereview.chromium.org/11316258/diff/7/sdk/lib/html/dart2js/html_dar...
sdk/lib/html/dart2js/html_dart2js.dart:6225: * Unless your webpage contains
multiple documents, the top level query
Sadly you can't link to a top level method in dart when there is a conflicting
member name.  This is a problem for dart code and for doc code.  hopefully at
some point there will be a fix for it for both cases.

On 2012/11/30 18:50:14, Kathy Walrath wrote:
> top level query -> top-level [query]
> 
> (top-level hyphenated because it's before the noun)
> 
> Could you please test how to link to the top-level query method? I'm not sure
> whether [query] will link to it or to this one. Thanks!

https://codereview.chromium.org/11316258/diff/7/sdk/lib/html/dart2js/html_dar...
sdk/lib/html/dart2js/html_dart2js.dart:6226: * method behaves the same as this
method so you should use it instead to
On 2012/11/30 18:50:14, Kathy Walrath wrote:
> method so you should use it -> method, so you can use it

Done.

https://codereview.chromium.org/11316258/diff/7/sdk/lib/html/dart2js/html_dar...
sdk/lib/html/dart2js/html_dart2js.dart:6249: * Unless your webpage contains
multiple documents, the top level queryAll
On 2012/11/30 18:50:14, Kathy Walrath wrote:
> same comments as for query description above

Done.

https://codereview.chromium.org/11316258/diff/7/sdk/lib/html/dart2js/html_dar...
sdk/lib/html/dart2js/html_dart2js.dart:7905: *     events['mouseover'].add((e)
=> print("Mouse over!"))
On 2012/11/30 18:50:14, Kathy Walrath wrote:
> Nice examples!
> 
> Add a ; to the end of each example.

Done.

[Kathy Walrath, 2012-11-30 21:39:18]

lgtm

[blois, 2012-11-30 21:42:58]

lgtm