Document the document class.

sdk/lib/html/dart2js/html_dart2js.dart

Index: sdk/lib/html/dart2js/html_dart2js.dart
diff --git a/sdk/lib/html/dart2js/html_dart2js.dart b/sdk/lib/html/dart2js/html_dart2js.dart
index b6d8612eaad1c799524fc5e5f0e68197573c73ac..e37c4b1e16d11925dafb4ae330de3fd5061c9f6f 100644
--- a/sdk/lib/html/dart2js/html_dart2js.dart
+++ b/sdk/lib/html/dart2js/html_dart2js.dart
@@ -6013,6 +6013,15 @@ class DivElement extends Element implements Element native "*HTMLDivElement" {
 
 
 /// @domName Document
+/**
+ * The base class for all documents.
+ *
+ * Each web page loaded in the browser has its own [Document] object, which is
+ * typically an [HtmlDocument].
+ *
+ * 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/).
+ */
 class Document extends Node  native "*Document"
 {
 
@@ -6024,6 +6033,7 @@ class Document extends Node  native "*Document"
   /// @domName Document.body; @docsEditable true
   Element get $dom_body => JS("Element", "#.body", this);
 
+  /// Moved to [HtmlDocument].
   /// @domName Document.body; @docsEditable true
   void set $dom_body(Element value) {
     JS("void", "#.body = #", this, value);
@@ -6035,6 +6045,7 @@ class Document extends Node  native "*Document"
   /// @domName Document.cookie; @docsEditable true
   String cookie;
 
+  /// Returns the [Window] associated with the document.
   /// @domName Document.defaultView; @docsEditable true
   Window get window => _convertNativeToDart_Window(this._window);
   dynamic get _window => JS("dynamic", "#.defaultView", this);
@@ -6045,12 +6056,14 @@ class Document extends Node  native "*Document"
   /// @domName Document.domain; @docsEditable true
   final String domain;
 
+  /// Moved to [HtmlDocument].
   /// @domName Document.head; @docsEditable true
   HeadElement get $dom_head => JS("HeadElement", "#.head", this);
 
   /// @domName Document.implementation; @docsEditable true
   final DOMImplementation implementation;
 
+  /// Moved to [HtmlDocument].
   /// @domName Document.lastModified; @docsEditable true
   String get $dom_lastModified => JS("String", "#.lastModified", this);
 
@@ -6060,41 +6073,52 @@ class Document extends Node  native "*Document"
   /// @domName Document.readyState; @docsEditable true
   final String readyState;
 
+  /// Moved to [HtmlDocument].
   /// @domName Document.referrer; @docsEditable true
   String get $dom_referrer => JS("String", "#.referrer", this);
 
   /// @domName Document.selectedStylesheetSet; @docsEditable true
   String selectedStylesheetSet;
 
+  /// Moved to [HtmlDocument].
   /// @domName Document.styleSheets; @docsEditable true
   List<StyleSheet> get $dom_styleSheets => JS("_StyleSheetList", "#.styleSheets", this);
 
+  /// Moved to [HtmlDocument].
   /// @domName Document.title; @docsEditable true
   String get $dom_title => JS("String", "#.title", this);
 
+  /// Moved to [HtmlDocument].
   /// @domName Document.title; @docsEditable true
   void set $dom_title(String value) {
     JS("void", "#.title = #", this, value);
   }
 
+  /// Moved to [HtmlDocument].
   /// @domName Document.webkitFullscreenElement; @docsEditable true
   Element get $dom_webkitFullscreenElement => JS("Element", "#.webkitFullscreenElement", this);
 
+  /// Moved to [HtmlDocument].
   /// @domName Document.webkitFullscreenEnabled; @docsEditable true
   bool get $dom_webkitFullscreenEnabled => JS("bool", "#.webkitFullscreenEnabled", this);
 
+  /// Moved to [HtmlDocument].
   /// @domName Document.webkitHidden; @docsEditable true
   bool get $dom_webkitHidden => JS("bool", "#.webkitHidden", this);
 
+  /// Moved to [HtmlDocument].
   /// @domName Document.webkitIsFullScreen; @docsEditable true
   bool get $dom_webkitIsFullScreen => JS("bool", "#.webkitIsFullScreen", this);
 
+  /// Moved to [HtmlDocument].
   /// @domName Document.webkitPointerLockElement; @docsEditable true
   Element get $dom_webkitPointerLockElement => JS("Element", "#.webkitPointerLockElement", this);
 
+  /// Moved to [HtmlDocument].
   /// @domName Document.webkitVisibilityState; @docsEditable true
   String get $dom_webkitVisibilityState => JS("String", "#.webkitVisibilityState", this);
 
+  /// Use the [Range] constructor instead.
   /// @domName Document.caretRangeFromPoint; @docsEditable true
   Range $dom_caretRangeFromPoint(int x, int y) native "caretRangeFromPoint";
 
@@ -6104,6 +6128,7 @@ class Document extends Node  native "*Document"
   /// @domName Document.createDocumentFragment; @docsEditable true
   DocumentFragment createDocumentFragment() native;
 
+  /// Deprecated: use new Element.tag(tagName) instead.
   /// @domName Document.createElement; @docsEditable true
   Element $dom_createElement(String tagName) native "createElement";
 
@@ -6126,9 +6151,11 @@ class Document extends Node  native "*Document"
   }
   Touch _createTouch_1(LocalWindow window, target, identifier, pageX, pageY, screenX, screenY, webkitRadiusX, webkitRadiusY, webkitRotationAngle, webkitForce) native "createTouch";
 
+  /// Use the [TouchList] constructor isntead.
   /// @domName Document.createTouchList; @docsEditable true
   TouchList $dom_createTouchList() native "createTouchList";
 
+  /// Moved to [HtmlDocument].
   /// @domName Document.elementFromPoint; @docsEditable true
   Element $dom_elementFromPoint(int x, int y) native "elementFromPoint";
 
@@ -6138,9 +6165,11 @@ class Document extends Node  native "*Document"
   /// @domName Document.getCSSCanvasContext; @docsEditable true
   CanvasRenderingContext getCssCanvasContext(String contextId, String name, int width, int height) native "getCSSCanvasContext";
 
+  /// Deprecated: use query("#$elementId") instead.
   /// @domName Document.getElementById; @docsEditable true
   Element $dom_getElementById(String elementId) native "getElementById";
 
+  /// Deprecated: use query("#$elementId") instead.
   /// @domName Document.getElementsByClassName; @docsEditable true
   @Returns('_NodeList') @Creates('_NodeList')
   List<Node> $dom_getElementsByClassName(String tagname) native "getElementsByClassName";
@@ -6168,6 +6197,7 @@ class Document extends Node  native "*Document"
   /// @domName Document.queryCommandValue; @docsEditable true
   String queryCommandValue(String command) native;
 
+  /// Deprecated: renamed to the shorter name [query].
   /// @domName Document.querySelector; @docsEditable true
   Element $dom_querySelector(String selectors) native "querySelector";
 
@@ -6175,17 +6205,34 @@ class Document extends Node  native "*Document"
   @Returns('_NodeList') @Creates('_NodeList')
   List<Node> $dom_querySelectorAll(String selectors) native "querySelectorAll";
 
+  /// Moved to [HtmlDocument].
   /// @domName Document.webkitCancelFullScreen; @docsEditable true
   void $dom_webkitCancelFullScreen() native "webkitCancelFullScreen";
 
+  /// Moved to [HtmlDocument].
   /// @domName Document.webkitExitFullscreen; @docsEditable true
   void $dom_webkitExitFullscreen() native "webkitExitFullscreen";
 
+  /// Moved to [HtmlDocument].
   /// @domName Document.webkitExitPointerLock; @docsEditable true
   void $dom_webkitExitPointerLock() native "webkitExitPointerLock";
 
-  // TODO(jacobr): implement all Element methods not on Document.
 
+  /**
+   * Finds the first descendant element of this document that matches the
+   * specified group of selectors.
+   *
+   * Unless your webpage contains multiple documents, the top level query

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

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!

[Jacob, 2012/11/30 20:59:51]

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:

+   * method behaves the same as this method so you should use it instead to

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

method so you should use it -> method, so you can use it

[Jacob, 2012/11/30 20:59:51]

Done.

+   * save typing a few characters.
+   *
+   * [selectors] should be a string using CSS selector syntax.
+   *     var element1 = document.query('.className');
+   *     var element2 = document.query('#id');
+   *
+   * For details about CSS selector syntax, see the
+   * [CSS selector specification](http://www.w3.org/TR/css3-selectors/).
+   */
   Element query(String selectors) {
     // It is fine for our RegExp to detect element id query selectors to have
     // false negatives but not false positives.
@@ -6195,6 +6242,20 @@ class Document extends Node  native "*Document"
     return $dom_querySelector(selectors);
   }
 
+  /**
+   * Finds all descendant elements of this document that match the specified
+   * group of selectors.
+   *
+   * Unless your webpage contains multiple documents, the top level queryAll

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

same comments as for query description above

[Jacob, 2012/11/30 20:59:51]

Done.

+   * method behaves the same as this method so you should use it instead to
+   * save typing a few characters.
+   *
+   * [selectors] should be a string using CSS selector syntax.
+   *     var items = document.queryAll('.itemClassName');
+   *
+   * For details about CSS selector syntax, see the
+   * [CSS selector specification](http://www.w3.org/TR/css3-selectors/).
+   */
   List<Element> queryAll(String selectors) {
     if (new RegExp("""^\\[name=["'][^'"]+['"]\\]\$""").hasMatch(selectors)) {
       final mutableMatches = $dom_getElementsByName(
@@ -6373,7 +6434,7 @@ class DocumentFragment extends Node native "*DocumentFragment" {
     }
     return null;
   }
-  Element get $m_lastElementChild() => elements.last;
+  Element get $m_lastElementChild => elements.last;
   Element get nextElementSibling => null;
   Element get previousElementSibling => null;
   Element get offsetParent => null;
@@ -7833,6 +7894,19 @@ class EventSourceEvents extends Events {
 // BSD-style license that can be found in the LICENSE file.
 
 
+/**
+ * Base class that supports listening for and dispatching browser events.
+ *
+ * Events can either be accessed by string name (using the indexed getter) or by
+ * getters exposed by subclasses. Use the getters exposed by subclasses when
+ * possible for better compile-time type checks.
+ * 
+ * Using an indexed getter:
+ *     events['mouseover'].add((e) => print("Mouse over!"))

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

Nice examples!

Add a ; to the end of each example.

[Jacob, 2012/11/30 20:59:51]

Done.

+ *
+ * Using a getter provided by a subclass:
+ *     elementEvents.mouseOver.add((e) => print("Mouse over!"))
+ */
 class Events {
   /* Raw event target. */
   final EventTarget _ptr;
@@ -7844,6 +7918,9 @@ class Events {
   }
 }
 
+/**
+ * Supports adding, removing, and dispatching events for a specific event type.
+ */
 class EventListenerList {
 
   final EventTarget _ptr;
@@ -7879,6 +7956,14 @@ class EventListenerList {
 }
 
 /// @domName EventTarget
+/**
+ * Base class for all browser objects that support events.
+ *
+ * Use the [on] property to add, remove, and dispatch events (rather than
+ * [$dom_addEventListener], [$dom_dispatchEvent], and
+ * [$dom_removeEventListener]) for compile-time type checks and a more concise
+ * API.
+ */ 
 class EventTarget native "*EventTarget" {
 
   /** @domName EventTarget.addEventListener, EventTarget.removeEventListener, EventTarget.dispatchEvent */
@@ -11181,7 +11266,7 @@ class LocalWindow extends EventTarget implements Window native "@*DOMWindow" {
   // API level getter and setter for Location.
   // TODO: The cross domain safe wrapper can be inserted here or folded into
   // _LocationWrapper.
-  LocalLocation get location() {
+  LocalLocation get location {
     // Firefox work-around for Location.  The Firefox location object cannot be
     // made to behave like a Dart object so must be wrapped.
     var result = _location;
@@ -11278,7 +11363,7 @@ class LocalWindow extends EventTarget implements Window native "@*DOMWindow" {
        this);
   }
 
-  IDBFactory get indexedDB() =>
+  IDBFactory get indexedDB =>
       JS('IDBFactory',
          '#.indexedDB || #.webkitIndexedDB || #.mozIndexedDB',
          this, this, this);