Document the document class.

sdk/lib/html/dart2js/html_dart2js.dart

 library html;
 
 import 'dart:isolate';
 import 'dart:json';
 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 5995 matching lines @@
 class DivElement extends Element implements Element native "*HTMLDivElement" {
 
   factory DivElement() => document.$dom_createElement("div");
 }
 // 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  native "*Document"
 {
 
 
   /// @domName EventTarget.addEventListener, EventTarget.removeEventListener, EventTarget.dispatchEvent; @docsEditable true
   DocumentEvents get on =>
     new DocumentEvents(this);
 
   /// @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);
   }
 
   /// @domName Document.charset; @docsEditable true
   String charset;
 
   /// @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);
 
   /// @domName Document.documentElement; @docsEditable true
   final Element documentElement;
 
   /// @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);
 
   /// @domName Document.preferredStylesheetSet; @docsEditable true
   final String preferredStylesheetSet;
 
   /// @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";
 
   /// @domName Document.createCDATASection; @docsEditable true
   CDATASection createCDataSection(String data) native "createCDATASection";
 
   /// @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";
 
   /// @domName Document.createElementNS; @docsEditable true
   Element $dom_createElementNS(String namespaceURI, String qualifiedName) native "createElementNS";
 
   /// @domName Document.createEvent; @docsEditable true
   Event $dom_createEvent(String eventType) native "createEvent";
 
   /// @domName Document.createRange; @docsEditable true
   Range createRange() native;
 
   /// @domName Document.createTextNode; @docsEditable true
   Text $dom_createTextNode(String data) native "createTextNode";
 
   /// @domName Document.createTouch; @docsEditable true
   Touch createTouch(LocalWindow window, EventTarget target, int identifier, int pageX, int pageY, int screenX, int screenY, int webkitRadiusX, int webkitRadiusY, num webkitRotationAngle, num webkitForce) {
     var target_1 = _convertDartToNative_EventTarget(target);
     return _createTouch_1(window, target_1, identifier, pageX, pageY, screenX, screenY, webkitRadiusX, webkitRadiusY, webkitRotationAngle, webkitForce);
   }
   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";
 
   /// @domName Document.execCommand; @docsEditable true
   bool execCommand(String command, bool userInterface, String value) native;
 
   /// @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";
 
   /// @domName Document.getElementsByName; @docsEditable true
   @Returns('_NodeList') @Creates('_NodeList')
   List<Node> $dom_getElementsByName(String elementName) native "getElementsByName";
 
   /// @domName Document.getElementsByTagName; @docsEditable true
   @Returns('_NodeList') @Creates('_NodeList')
   List<Node> $dom_getElementsByTagName(String tagname) native "getElementsByTagName";
 
   /// @domName Document.queryCommandEnabled; @docsEditable true
   bool queryCommandEnabled(String command) native;
 
   /// @domName Document.queryCommandIndeterm; @docsEditable true
   bool queryCommandIndeterm(String command) native;
 
   /// @domName Document.queryCommandState; @docsEditable true
   bool queryCommandState(String command) native;
 
   /// @domName Document.queryCommandSupported; @docsEditable true
   bool queryCommandSupported(String command) native;
 
   /// @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";
 
   /// @domName Document.querySelectorAll; @docsEditable true
   @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.
     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

[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(
           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 158 matching lines @@
   String get title => "";
   String get tagName => "";
   String get webkitdropzone => "";
   String get webkitRegionOverflow => "";
   Element get $m_firstElementChild {
     if (elements.length > 0) {
       return elements[0];
     }
     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;
   Element get parent => null;
   Map<String, String> get attributes => const {};
   CssClassSet get classes => new _FrozenCssClassSet();
   Map<String, String> get dataAttributes => const {};
   CSSStyleDeclaration get style => new Element.tag('div').style;
   Future<CSSStyleDeclaration> get computedStyle =>
       _emptyStyleFuture();
@@ skipping 1439 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!"))

[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;
 
   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 native "*EventTarget" {
 
   /** @domName EventTarget.addEventListener, EventTarget.removeEventListener, EventTarget.dispatchEvent */
   Events get on => new Events(this);
 
   /// @domName EventTarget.addEventListener; @docsEditable true
   void $dom_addEventListener(String type, EventListener listener, [bool useCapture]) native "addEventListener";
 
   /// @domName EventTarget.dispatchEvent; @docsEditable true
   bool $dom_dispatchEvent(Event event) native "dispatchEvent";
@@ skipping 3282 matching lines @@
     if (options == null) {
       return _DOMWindowCrossFrame._createSafe(_open2(url, name));
     } else {
       return _DOMWindowCrossFrame._createSafe(_open3(url, name, options));
     }
   }
 
   // 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;
     if (_isDartLocation(result)) return result;  // e.g. on Chrome.
     if (null == _location_wrapper) {
       _location_wrapper = new _LocationWrapper(result);
     }
     return _location_wrapper;
   }
 
@@ skipping 76 matching lines @@
    $this.requestAnimationFrame = function(callback) {
       return window.setTimeout(function() {
         callback(Date.now());
       }, 16 /* 16ms ~= 60fps */);
    };
    $this.cancelAnimationFrame = function(id) { clearTimeout(id); }
   })(#)""",
        this);
   }
 
-  IDBFactory get indexedDB() =>
+  IDBFactory get indexedDB =>
       JS('IDBFactory',
          '#.indexedDB || #.webkitIndexedDB || #.mozIndexedDB',
          this, this, this);
 
   /**
    * Lookup a port by its [name].  Return null if no port is
    * registered under [name].
    */
   SendPortSync lookupPort(String name) {
     var port = JSON.parse(document.documentElement.attributes['dart-port:$name']);
@@ skipping 13167 matching lines @@
     if (length < 0) throw new ArgumentError('length');
     if (start < 0) throw new RangeError.value(start);
     int end = start + length;
     if (end > a.length) throw new RangeError.value(end);
     for (int i = start; i < end; i++) {
       accumulator.add(a[i]);
     }
     return accumulator;
   }
 }