First part of remembering platform app window geometry.

chrome/common/extensions/api/app_window.idl

Index: chrome/common/extensions/api/app_window.idl
diff --git a/chrome/common/extensions/api/app_window.idl b/chrome/common/extensions/api/app_window.idl
index 7c61e06b6f3cc4e287d4d8536d2bdb045abc9958..c0c47079347984b7e2fd2d8aa1945298c5eb02fd 100644
--- a/chrome/common/extensions/api/app_window.idl
+++ b/chrome/common/extensions/api/app_window.idl
@@ -6,6 +6,21 @@
 
 namespace app.window {
   dictionary CreateWindowOptions {
+    // Id to identify the window.

[jeremya, 2012/08/30 04:49:33]

Perhaps this comment should be expanded a little? This is the first thing
visible on the docs (http://developer.chrome.com/apps/app.window.html)

[Marijn Kruisselbrink, 2012/08/30 17:15:05]

Yeah, I tried to add the comment below for the create() method to actually apply
to the CreateWindowOptions dictionary, but comments there seem to be ignored by
the docs generator. Expanded this comment at least a little bit now.

+    DOMString? id;
+
+    // Default width of the window.
+    long? defaultWidth;
+
+    // Default height of the window.
+    long? defaultHeight;
+
+    // Default X coordinate of the window.
+    long? defaultLeft;
+
+    // Default Y coordinate of the window.
+    long? defaultTop;
+
     // Width of the window.
     long? width;
 
@@ -41,6 +56,31 @@ namespace app.window {
       void ([instanceOf=global] object created_window);
 
   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.
+    //
+    // 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 on subsequent
+    // opening of a window with the same id. The defaultLeft/defaultTop and
+    // defaultWidth/defaultHeight properties can be used to specify a position
+    // and size when no geometry has been stored for the window yet.
+    //
+    // 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.
     static void create(DOMString url,
                        optional CreateWindowOptions options,
                        optional CreateWindowCallback callback);