Added some more documentation to top level Window.

Added some more documentation to top level Window.

R=kathyw@google.com

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

[blois, 2013-07-11 17:03:57]

https://codereview.chromium.org/19058002/diff/1/tools/dom/templates/html/dart...
File tools/dom/templates/html/dart2js/html_dart2js.darttemplate (right):

https://codereview.chromium.org/19058002/diff/1/tools/dom/templates/html/dart...
tools/dom/templates/html/dart2js/html_dart2js.darttemplate:81: Window get window
=> JS('Window', 'window');
Can you duplicate this into the Dartium version as well?

[Kathy Walrath, 2013-07-11 17:15:34]

Yay, docs! I think we could make this clearer, though.

https://codereview.chromium.org/19058002/diff/1/tools/dom/templates/html/dart...
File tools/dom/templates/html/dart2js/html_dart2js.darttemplate (right):

https://codereview.chromium.org/19058002/diff/1/tools/dom/templates/html/dart...
tools/dom/templates/html/dart2js/html_dart2js.darttemplate:66: * The current
window.
You don't want to confuse an on-screen window with the window object. So maybe
instead:

The top-level window object, which represents this web page's container (a tab
or the tab's window, usually).

https://codereview.chromium.org/19058002/diff/1/tools/dom/templates/html/dart...
tools/dom/templates/html/dart2js/html_dart2js.darttemplate:71: * Each page's
[Window] has an associated [HtmlDocument] that represents the
Why is this paragraph here? Either delete it or make the relationship clearer.

It seems like maybe this should be removed and the document description should
be:

The top-level document, representing the content of this page.

https://codereview.chromium.org/19058002/diff/1/tools/dom/templates/html/dart...
tools/dom/templates/html/dart2js/html_dart2js.darttemplate:74: * This getter
usually retuns the only [Window] on the page, but any `<iframe>`
retuns -> returns

Maybe combine this into the previous paragraph?

[Andrei Mouravski, 2013-07-11 18:20:46]

PTAL.

https://codereview.chromium.org/19058002/diff/1/tools/dom/templates/html/dart...
File tools/dom/templates/html/dart2js/html_dart2js.darttemplate (right):

https://codereview.chromium.org/19058002/diff/1/tools/dom/templates/html/dart...
tools/dom/templates/html/dart2js/html_dart2js.darttemplate:66: * The current
window.
On 2013/07/11 17:15:35, Kathy Walrath wrote:
> You don't want to confuse an on-screen window with the window object. So maybe
> instead:
> 
> The top-level window object, which represents this web page's container (a tab
> or the tab's window, usually).
> 

Done.

https://codereview.chromium.org/19058002/diff/1/tools/dom/templates/html/dart...
tools/dom/templates/html/dart2js/html_dart2js.darttemplate:71: * Each page's
[Window] has an associated [HtmlDocument] that represents the
On 2013/07/11 17:15:35, Kathy Walrath wrote:
> Why is this paragraph here? Either delete it or make the relationship clearer.
> 
> It seems like maybe this should be removed and the document description should
> be:
> 
> The top-level document, representing the content of this page.

Done.

[Kathy Walrath, 2013-07-11 18:31:39]

Better! Still a quibble with the iframe description.

https://codereview.chromium.org/19058002/diff/6001/sdk/lib/html/dart2js/html_...
File sdk/lib/html/dart2js/html_dart2js.dart (right):

https://codereview.chromium.org/19058002/diff/6001/sdk/lib/html/dart2js/html_...
sdk/lib/html/dart2js/html_dart2js.dart:46: * This getter usually retuns the only
[Window] on the page, but any `<iframe>`
retuns -> returns

This sentence makes it sound like this getter might sometimes return another
window or multiple windows. Maybe (as a continuation of the paragraph above):

If the web page has `<iframe>`s, then each iframe has its own window object,
which is accessible only to that iframe.

[Andrei Mouravski, 2013-07-11 20:52:05]

PTAL.

https://codereview.chromium.org/19058002/diff/6001/sdk/lib/html/dart2js/html_...
File sdk/lib/html/dart2js/html_dart2js.dart (right):

https://codereview.chromium.org/19058002/diff/6001/sdk/lib/html/dart2js/html_...
sdk/lib/html/dart2js/html_dart2js.dart:46: * This getter usually retuns the only
[Window] on the page, but any `<iframe>`
On 2013/07/11 18:31:39, Kathy Walrath wrote:
> retuns -> returns
> 
> This sentence makes it sound like this getter might sometimes return another
> window or multiple windows. Maybe (as a continuation of the paragraph above):
> 
> If the web page has `<iframe>`s, then each iframe has its own window object,
> which is accessible only to that iframe. 

Done.

[Kathy Walrath, 2013-07-11 22:59:45]

https://codereview.chromium.org/19058002/diff/5118776383111168/sdk/lib/html/d...
File sdk/lib/html/dart2js/html_dart2js.dart (right):

https://codereview.chromium.org/19058002/diff/5118776383111168/sdk/lib/html/d...
sdk/lib/html/dart2js/html_dart2js.dart:46: * If the web page has any `<iframe>`
elements, then each `iframe` has its own
I would use either iframe or `<iframe>` (never `iframe`), but otherwise lgtm.

[Andrei Mouravski, 2013-07-11 23:04:11]

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