Improve app.window documentation

chrome/common/extensions/api/app_window.idl

 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 namespace app.window {
   dictionary Bounds {
     long? left;
     long? top;
     long? width;
     long? height;
   };
 
   // State of a window: normal, fullscreen, maximized, minimized.
   enum State { normal, fullscreen, maximized, minimized };
 
   // 'shell' is the default window type. 'panel' is managed by the OS
   // (Currently experimental, Ash only).
   [nodoc] enum WindowType { shell, panel };
 
   dictionary CreateWindowOptions {
     // Id to identify the window. This will be used to remember the size
     // and position of the window and restore that geometry when a window
-    // with the same id (and no explicit size or position) is later opened.
+    // with the same id is later opened.
     DOMString? id;
 
     // Default width of the window. (Deprecated; regular bounds act like this
     // now.)
     [nodoc] long? defaultWidth;
 
     // Default height of the window. (Deprecated; regular bounds act like this
     // now.)
     [nodoc] long? defaultHeight;
 
@@ skipping 28 matching lines @@
 
     // Maximum height for the lifetime of the window.
     long? maxHeight;
 
     // Type of window to create.
     [nodoc] WindowType? type;
 
     // Frame type: 'none' or 'chrome' (defaults to 'chrome').
     DOMString? frame;
 
-    // Size of the content in the window (excluding the titlebar). If specified
-    // in addition to any of the deprecated left/top/width/height parameters,
-    // this field takes precedence.
+    // Size and position of the content in the window (excluding the titlebar).
+    // If an id is also specified and a window with a matching id has been shown
+    // before, the remembered bounds of the window will be used instead.
+    // If specified in addition to any of the deprecated left/top/width/height
+    // parameters, this field takes precedence.

[jeremya, 2013/04/12 17:09:07]

Perhaps we could remove this comment about the deprecated parameters? They've
been undocumented for a while.

[benwells, 2013/05/07 11:43:56]

Done.

     Bounds? bounds;
 
     // Enable window background transparency.
     // Only supported in ash. Requires experimental API permission.
     boolean? transparentBackground;
 
     // The initial state of the window, allowing it to be created already
     // fullscreen, maximized, or minimized. Defaults to 'normal'.
     State? state;
 
@@ skipping 75 matching lines @@
     // The JavaScript 'window' object for the created child.
     [instanceOf=global] object contentWindow;
   };
 
   interface Functions {
     // The size and position of a window can be specified in a number of
     // different ways. The most simple option is not specifying anything at
     // all, in which case a default size and platform dependent position will
     // be used.
     //
-    // Another option is to use the top/left and width/height properties,
-    // which will always put the window at the specified coordinates with the
-    // specified size.
+    // Another option is to use the bounds property, which will put the window
+    // at the specified coordinates with the specified size. If the window has
+    // a frame, it's total size will be the size given plus the size of the
+    // frame; that is, the size in bounds is the content size, not the window
+    // size.
     //
-    // Yet another option is to give the window a (unique) id. This id is then
-    // used to remember the size and position of the window whenever it is
-    // moved or resized. This size and position is then used instead of the
-    // specified bounds on subsequent opening of a window with the same id. If
-    // you need to open a window with an id at a location other than the
-    // remembered default, you can create it hidden, move it to the desired
-    // location, then show it.
-    //
-    // You can also combine these various options, explicitly specifying for
-    // example the size while having the position be remembered or other
-    // combinations like that. Size and position are dealt with seperately,
-    // but individual coordinates are not. So if you specify a top (or left)
-    // coordinate, you should also specify a left (or top) coordinate, and
-    // similar for size.
-    //
-    // If you specify both a regular and a default value for the same option
-    // the regular value is the only one that takes effect.
+    // To automatically remember the positions of windows you can give them ids.
+    // If a window has an id, This id is used to remember the size and position
+    // of the window whenever it is moved or resized. This size and position is
+    // then used instead of the specified bounds on subsequent opening of a
+    // window with the same id. If you need to open a window with an id at a
+    // location other than the remembered default, you can create it hidden,
+    // move it to the desired location, then show it.
     static void create(DOMString url,
                        optional CreateWindowOptions options,
                        optional CreateWindowCallback callback);
 
     // Returns an $ref:AppWindow object for the
     // current script context (ie JavaScript 'window' object). This can also be
     // called on a handle to a script context for another page, for example:
     // otherWindow.chrome.app.window.current().
     [nocompile] static AppWindow current();
     [nocompile, nodoc] static void initializeAppWindow(object state);
@@ skipping 12 matching lines @@
     // Fired when the window is maximized.
     [nocompile] static void onMaximized();
 
     // Fired when the window is minimized.
     [nocompile] static void onMinimized();
 
     // Fired when the window is restored from being minimized or maximized.
     [nocompile] static void onRestored();
   };
 };