Document the document class.

sdk/lib/html/dartium/html_dartium.dart

 library html;
 
 import 'dart:isolate';
 import 'dart:json';
 import 'dart:nativewrappers';
 import 'dart:svg' as svg;
 import 'dart:web_audio' as web_audio;
 // 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.
@@ skipping 7638 matching lines @@
   factory DivElement() => document.$dom_createElement("div");
   DivElement.internal(): super.internal();
 
 }
 // 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.
 
 
 /// @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 
 {
 
   Document.internal(): super.internal();
 
   /// @domName EventTarget.addEventListener, EventTarget.removeEventListener, EventTarget.dispatchEvent; @docsEditable true
   DocumentEvents get on =>
     new DocumentEvents(this);
 
 
@@ skipping 201 matching lines @@
   void $dom_webkitCancelFullScreen() native "Document_webkitCancelFullScreen_Callback";
 
 
   /** @domName Document.webkitExitFullscreen */
   void $dom_webkitExitFullscreen() native "Document_webkitExitFullscreen_Callback";
 
 
   /** @domName Document.webkitExitPointerLock */
   void $dom_webkitExitPointerLock() native "Document_webkitExitPointerLock_Callback";
 
-  // 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
+   * 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 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.
     if (new RegExp("^#[_a-zA-Z]\\w*\$").hasMatch(selectors)) {
       return $dom_getElementById(selectors.substring(1));
     }
     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
+   * 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(
           selectors.substring(7,selectors.length - 2));
       int len = mutableMatches.length;
       final copyOfMatches = new List<Element>(len);
       for (int i = 0; i < len; ++i) {
         copyOfMatches[i] = mutableMatches[i];
       }
       return new _FrozenElementList._wrap(copyOfMatches);
@@ skipping 1801 matching lines @@
 
   EventListenerList get message => this['message'];
 
   EventListenerList get open => this['open'];
 }
 // 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.
 
 
+/**
+ * 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!"));
+ *
+ * Using a getter provided by a subclass:
+ *     elementEvents.mouseOver.add((e) => print("Mouse over!"));
+ */
 class Events {
   /* Raw event target. */
   final EventTarget _ptr;
 
   Events(this._ptr);
 
   EventListenerList operator [](String type) {
     return new EventListenerList(_ptr, type);
   }
 }
 
+/**
+ * Supports adding, removing, and dispatching events for a specific event type.
+ */
 class EventListenerList {
 
   final EventTarget _ptr;
   final String _type;
 
   EventListenerList(this._ptr, this._type);
 
   // TODO(jacobr): implement equals.
 
   EventListenerList add(EventListener listener,
@@ skipping 15 matching lines @@
   void _add(EventListener listener, bool useCapture) {
     _ptr.$dom_addEventListener(_type, listener, useCapture);
   }
 
   void _remove(EventListener listener, bool useCapture) {
     _ptr.$dom_removeEventListener(_type, listener, useCapture);
   }
 }
 
 /// @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 extends NativeFieldWrapperClass1 {
 
   /** @domName EventTarget.addEventListener, EventTarget.removeEventListener, EventTarget.dispatchEvent */
   Events get on => new Events(this);
   EventTarget.internal();
 
 
   /** @domName EventTarget.addEventListener */
   void $dom_addEventListener(String type, EventListener listener, [bool useCapture]) native "EventTarget_addEventListener_Callback";
 
@@ skipping 20040 matching lines @@
   bool get isEmpty => Maps.isEmpty(this);
 }
 
 get _printClosure => (s) {
   try {
     window.console.log(s);
   } catch (_) {
     _Utils.print(s);
   }
 };