Window.close documentation.

sdk/lib/html/src/CrossFrameTypes.dart

 // 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.
 
 part of html;
 
 /**
  * An object representing the top-level context object for web scripting.
  *
  * In a web browser, a [Window] object represents the actual browser window.
@@ skipping 15 matching lines @@
   /**
    * The current location of this window.
    *
    *     Location currentLocation = window.location;
    *     print(currentLocation.href); // 'http://www.example.com:80/'
    */
   Location get location;
   History get history;
 
   /**
-   * Indicates whether this window is closed.
+   * Indicates whether this window has been closed.
    *
    *     print(window.closed); // 'false'
    *     window.close();
    *     print(window.closed); // 'true'
    */
   bool get closed;
 
   /**
    * A reference to the window that opened this one.
    *
@@ skipping 32 matching lines @@
    *     myIFrame.elements.add(innerIFrame);
    *
    *     print(myIframe.contentWindow.top == window) // 'true'
    *     print(innerIFrame.contentWindow.top == window) // 'true'
    *
    *     print(window.top == window) // 'true'
    */
   Window get top;
 
   // Methods.
+  /**
+   * Closes the window.
+   *
+   * This method should only succeed if the [Window] object is
+   * **script-closeable** and the window calling [close] is allowed to navigate
+   * the window.
+   *
+   * A window is script-closeable if it is either a window
+   * that was opened by another window, or if it is a window with only one
+   * document in its history.
+   *
+   * A window might not be allowed to navigate, and therefore close, another
+   * window due to browser security features.
+   *
+   *     var other = window.open('http://www.example.com', 'foo');
+   *     // Closes other window, as it is script-closeable.
+   *     other.close();
+   *     print(other.closed()); // 'true'
+   *
+   *     window.location('http://www.mysite.com', 'foo');
+   *     // Does not close this window, as the history has changed.
+   *     window.close();
+   *     print(window.closed()); // 'false'
+   *
+   * See also:
+   *
+   * * [Window close discussion](http://www.w3.org/TR/html5/browsers.html#dom-window-close) from the W3C
+   */
   void close();
   void postMessage(var message, String targetOrigin, [List messagePorts = null]);
 }
 
 abstract class Location {
   void set href(String val);
 }
 
 abstract class History {
   void back();
   void forward();
   void go(int distance);
 }