First part of remembering platform app window geometry.

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.
 
 // File-level comment to appease parser. Eventually this will not be necessary.
 
 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;
 
     // Height of the window.
     long? height;
 
     // X coordinate of the window.
     long? left;
 
     // Y coordinate of the window.
@@ skipping 15 matching lines @@
     DOMString? type;
 
     // Frame type: 'none' or 'chrome' (defaults to 'chrome').
     DOMString? frame;
   };
 
   callback CreateWindowCallback =
       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);
 
     static void focus();
     static void maximize();
     static void minimize();
     static void restore();
     [nocompile] static void moveTo(long x, long y);
     [nocompile] static void resizeTo(long width, long height);
   };
 };