Added some more documentation to top level Window.

tools/dom/templates/html/dart2js/html_dart2js.darttemplate

 // Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 // DO NOT EDIT - unless you are editing documentation as per:
 // https://code.google.com/p/dart/wiki/ContributingHTMLDocumentation
 // Auto-generated dart:html library.
 
 /// The Dart HTML library.
 ///
@@ skipping 45 matching lines @@
 part '$AUXILIARY_DIR/WrappedList.dart';
 part '$AUXILIARY_DIR/dart2js_Conversions.dart';
 part '$AUXILIARY_DIR/dart2js_DOMImplementation.dart';
 part '$AUXILIARY_DIR/dart2js_KeyEvent.dart';
 part '$AUXILIARY_DIR/dart2js_LocationWrapper.dart';
 part '$AUXILIARY_DIR/dart2js_Platform.dart';
 part '$AUXILIARY_DIR/_ListIterators.dart';
 
 
 /**
- * The top-level Window object.
+ * The current window.

[Kathy Walrath, 2013/07/11 17:15:35]

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

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

Done.

+ *
+ * Each web page loaded in the browser has its own [Window], which is a
+ * container for the web page.
+ *
+ * Each page's [Window] has an associated [HtmlDocument] that represents the

[Kathy Walrath, 2013/07/11 17:15:35]

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.

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

Done.

+ * content of the page.
+ *
+ * This getter usually retuns the only [Window] on the page, but any `<iframe>`

[Kathy Walrath, 2013/07/11 17:15:35]

retuns -> returns

Maybe combine this into the previous paragraph?

+ * elements have their own [Window].
+ *
+ * See also:
+ *
+ *   * [Window](https://developer.mozilla.org/en-US/docs/Web/API/window) from MDN.
  */
 Window get window => JS('Window', 'window');

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

Can you duplicate this into the Dartium version as well?

 
 /**
  * The top-level Document object.
  */
 HtmlDocument get document => JS('HtmlDocument', 'document');
 
 Element query(String selector) => document.query(selector);
 ElementList queryAll(String selector) => document.queryAll(selector);
 
 // Workaround for tags like <cite> that lack their own Element subclass --
 // Dart issue 1990.
 class _HTMLElement extends Element native "HTMLElement" {
 }
 
 // Support for Send/ReceivePortSync.
 int _getNewIsolateId() {
   if (JS('bool', r'!window.$dart$isolate$counter')) {
     JS('void', r'window.$dart$isolate$counter = 1');
   }
   return JS('int', r'window.$dart$isolate$counter++');
 }
 
 // Fast path to invoke JS send port.
 _callPortSync(int id, message) {
   return JS('var', r'ReceivePortSync.dispatchCall(#, #)', id, message);
 }
 
 Future<SendPort> spawnDomFunction(Function f) =>
   new Future.value(IsolateNatives.spawnDomFunction(f));