Reland http://codereview.chromium.org/155945 which was erroneously reverted.

TBR=estade

Review URL: http://codereview.chromium.org/159240

git-svn-id: svn://svn.chromium.org/chrome/trunk/src@21338 0039d316-1c4b-4281-b951-d872f2087c98

6 files changed, 574 insertions, 341 deletions

diff --git a/chrome/common/extensions/api/bookmarks.json b/chrome/common/extensions/api/bookmarks.json
deleted file mode 100755
index 8f3bf07..0000000
--- a/chrome/common/extensions/api/bookmarks.json
+++ /dev/null
@@ -1,99 +0,0 @@
-{
-  "namespace": "chrome.bookmarks",
-  "types": [
-    {
-      "id": "BookmarkTreeNode",
-      "properties": {
-        "id": {
-          "type": "integer"
-        },
-        "title": {
-          "type": "string"
-        },
-        "parentId": {
-          "type": "integer"
-        },
-        "url": {
-          "type": "string"
-        },
-        "children": {
-          "type": "array",
-          "items": {
-            "$ref": "BookmarkTreeNode"
-          }
-        },
-        "dateAdded": {
-          "type": "integer"
-        },
-        "dateGroupModified": {
-          "type": "integer"
-        }
-      }
-    }
-  ],
-  "functions": [
-    {
-      "name": "create",
-      "description": "<p>Creates a new bookmark. To get the newly created bookmark (or just find out whether its creation succeeded), you need to specify a callback function.</p><p>If you specify a <code>url</code> </span>in the <var>bookmark</var> parameter, the new bookmark represents a URL; otherwise, it represents a group.</p><p>For more information about bookmark properties, see the <a href='#TOC-Description'>Description</a> section.</p>",
-      "parameters": [
-        { 
-          "name": "parentId",
-          "description": "The requested value of the new bookmark's <code>parentId</code> property.",
-          "type": "integer",
-          "minimum": 0,
-          "optional": true
-        },
-        {
-          "name": "index",
-          "description": "The desired <code>index</code> position (0-based) at which this bookmark should be created. If absent, it will be placed at the end.",
-          "type": "integer",
-          "minimum": 0,
-          "optional": true
-        },
-        {
-          "name": "title",
-          "description": "The <code>title</code> string to be displayed to the user on in the bookmarks system.",
-          "type": "string",
-          "optional": true
-        },
-        {
-          "name": "url",
-          "description": "The destination URL of this bookmark.",
-          "type": "string",
-          "optional": true
-        },
-        { 
-          "name": "callback",
-          "description": "Function to callback upon completion.",
-          "type": "function",
-          "optional": true
-        }
-      ],
-      "callbackParameters" : [
-        {
-          "name": "result",
-          "$ref": "BookmarkTreeNode",
-          "description": "The BookmarkTreeNode that was created in the bookmarks system."
-        }
-      ]
-    }
-  ],
-  "events": [
-    {
-      "name": "onAdded",
-      "description": "Sent whenever a bookmark is added.",
-      "parameters": [
-        {
-          "name": "id",
-          "type": "integer",
-          "description": "The id of the BookmarkTreeNode that was added."
-        },
-        {
-          "name": "node",
-          "$ref": "BookmarkTreeNode",
-          "description": "The properties of the BookmarkTreeNode that was added."
-        }
-      ]
-    }
-  ]
-}
\ No newline at end of file
diff --git a/chrome/common/extensions/api/extension_api.json b/chrome/common/extensions/api/extension_api.json
index b2c30a3..759d17a 100755
--- a/chrome/common/extensions/api/extension_api.json
+++ b/chrome/common/extensions/api/extension_api.json
@@ -1,4 +1,75 @@
+// Copyright (c) 2009 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.
+
+/*
+ * This file defines the extensions api functions, events and types. It is
+ * json-structured list of api "modules". Each module has
+ *
+ *    namespace: "<apiname>", // i.e. "windows" which becomes visible to
+ *                            // extensions as chrome.windows.
+ *
+ *    types: [],              // a list of json schemas which define "types"
+ *                            // that are common to that module. i.e. "Tab" or
+ *                            // "BookmarkTreeNode".
+ *
+ *    functions: [],          // a list of json schemas which define the 
+ *                            // functions in the current module. i.e.
+ *                            // chrome.tabs.getCurrent().
+ *
+ *    events: [],             // a list of json schemas which define the events
+ *                            // which this module defines. i.e.
+ *                            // chrome.windows.onCreated.
+ *
+ *    --Functions Schemas--
+ *    Each function schema is required to have a 
+ *      
+ *       name: "<function name>"
+ *       type: "function"
+ *       description: "..." // this appears in the docs.
+ *       parameters: []
+ * 
+ *    |parameters| is a list of json schemas which define the list of parameters
+ *    this function requires and will be validated against. Each parameter
+ *    should define a "name" property, and "description" property, both of which
+ *    will appear in the docs. The final parameter may be a type: "function"
+ *    which is expected to be the callback for this call. That parameter, should
+ *    itself be named ("name": "callback"), have a "parameters" member that
+ *    is a list of the json schemas that define the types that the callback
+ *    sends. Callback parameters should also have "name" and "description"
+ *    properties.
+ *
+ *    --Event Schemas--
+ *    Each event schema is also a type: "function" schema that is named. It's
+ *    structure is the same as the callback functions for module Functions.
+ *    It should have a "name", "description", and a "parameters" describing
+ *    the set of arguments it sends.
+ *
+ *    --Referenced Types--
+ *    The "types": [] list may contain a list of types that are common to the
+ *    current api module. Each type should have an "id" member ("id": "Tab").
+ *    These types can be referenced from a schema with "$ref": "<idName>".
+ *    i.e. 
+ *  
+ *        ...
+ *        type: "function",
+ *        parameters: [
+ *          {$ref: "BookmarkTreeNode", name: "node"}
+ *        ]
+ *
+ *    WARNING: Do not use these referenced types in module function parameters.
+ *    They are not yet properly validated. They are currently safe to use in
+ *    callback parameters and event parameters.
+ *   
+ *    TODO(rafaelw): Validate callback arguments in debug and unittests
+ *    TODO(rafaelw): Validate event arguments in debug and unittests
+ *    TODO(rafaelw): Support $ref for json_schema validation.
+ */
+
 [
+  /**
+   * chrome.windows
+   */
   {
     namespace: "windows",
     types: [],
@@ -113,9 +184,27 @@
       }
     ]
   },
+
+  /**
+   * chrome.tabs
+   */
   {
     namespace: "tabs",
-    types: [],
+    types: [
+    {
+      id: "Tab",
+      type: "object",
+      properties: {
+        id: {type: "integer", minimum: 0},
+        index: {type: "integer", minimum: 0},
+        windowId: {type: "integer", minimum: 0},
+        selected: {type: "boolean"},
+        url: {type: "string"},
+        title: {type: "string", optional: true},
+        favIconUrl: {type: "string", optional: true}
+      }
+    }
+    ],
     functions: [
       {
         name: "get",
@@ -123,7 +212,13 @@
         description: "",
         parameters: [
           {type: "integer", name: "tabId", minimum: 0},
-          {type: "function", name: "callback"}
+          {
+            type: "function",
+            name: "callback",
+            parameters: [
+              {name: "tab", $ref: "Tab"}
+            ]
+          }
         ]
       },
       {
@@ -132,7 +227,13 @@
         description: "",
         parameters: [
           {type: "integer", name: "windowId", minimum: 0, optional: true},
-          {type: "function", name: "callback"}
+          {
+            type: "function", 
+            name: "callback",
+            parameters: [
+              {name: "tab", $ref: "Tab"}
+            ]
+          }
         ]
       },
       {
@@ -159,7 +260,14 @@
               selected: {type: "boolean", optional: true}
             }
           },
-          {type: "function", name: "callback", optional: true}
+          {
+            type: "function",
+            name: "callback",
+            optional: true, 
+            parameters: [
+              {name: "tab", $ref: "Tab"}
+            ]
+          }
         ]
       },
       {
@@ -176,7 +284,7 @@
               selected: {type: "boolean", optional: true}
             }
           },
-          {type: "function", name: "callback", optional: true}
+          {type: "function", name: "callback", optional: true, parameters: []}
         ]
       },
       {
@@ -193,7 +301,7 @@
               index: {type: "integer", minimum: 0}
             }
           },
-          {type: "function", name: "callback", optional: true}
+          {type: "function", name: "callback", optional: true, parameters: []}
         ]
       },
       {
@@ -202,7 +310,7 @@
         description: "",
         parameters: [
           {type: "integer", name: "tabId", minimum: 0, optional: true},
-          {type: "function", name: "callback", optional: true}
+          {type: "function", name: "callback", optional: true, parameters: []}
         ]
       },
       {
@@ -211,7 +319,13 @@
         description: "detect language of tab.",
         parameters: [
           {type: "integer", name: "tabId", minimum: 0, optional: true},
-          {type: "function", name: "callback"}
+          {
+            type: "function",
+            name: "callback",
+            parameters: [
+              {type: "string", name: "language"}
+            ]
+          }
         ]
       }
     ],
@@ -221,7 +335,7 @@
         type: "function",
         description: "",
         parameters: [
-          {type: "Object", name: "Tab"}
+          {$ref: "Tab", name: "tab"}
         ]
       },
       {
@@ -230,7 +344,15 @@
         description: "",
         parameters: [
           {type: "integer", name: "tabId", minimum: 0},
-          {type: "Object", name: "ChangedProps"}
+          {
+            type: "object",
+            name: "ChangedProps",
+            properties: {
+              tabId: {type: "integer", name: "tabId", minimum: 0},
+              status: {type: "string"},
+              url: {type: "string", optional: true}
+            }
+          }
         ]
       },
       {
@@ -239,7 +361,15 @@
         description: "",
         parameters: [
           {type: "integer", name: "tabId", minimum: 0},
-          {type: "Object", name: "MoveInfo"}
+          {
+            type: "object",
+            name: "MoveInfo",
+            properties: {
+              windowId: {type: "integer", minimum: 0},
+              fromIndex: {type: "integer", minimum: 0},
+              toIndex: {type: "integer", minimum: 0}
+            }
+          }
         ]
       },
       {
@@ -248,7 +378,12 @@
         description: "",
         parameters: [
           {type: "integer", name: "tabId", minimum: 0},
-          {type: "Object", name: "SelectionInfo"}
+          {
+            type: "object", name: "SelectInfo",
+            properties: {
+              windowId: {type: "integer", minimum: 0},
+            }
+          }
         ]
       },
       {
@@ -257,7 +392,14 @@
         description: "",
         parameters: [
           {type: "integer", name: "tabId", minimum: 0},
-          {type: "Object", name: "AttachInfo"}
+          {
+            type: "object",
+            name: "AttachInfo",
+            properties: {
+              newWindowId: {type: "integer", minimum: 0},
+              newPosition: {type: "integer", minimum: 0}
+            }
+          }
         ]
       },
       {
@@ -266,7 +408,14 @@
         description: "",
         parameters: [
           {type: "integer", name: "tabId", minimum: 0},
-          {type: "Object", name: "DetachInfo"}
+          {
+            type: "object",
+            name: "DetachInfo",
+            properties: {
+              oldWindowId: {type: "integer", minimum: 0},
+              oldPosition: {type: "integer", minimum: 0}
+            }
+          }
         ]
       },
       {
@@ -279,6 +428,10 @@
       }
     ]
   },
+
+  /**
+   * chrome.pageActions
+   */
   {
     namespace: "pageActions",
     types: [],
@@ -323,6 +476,10 @@
     events: [
     ]
   },
+
+  /**
+   * chrome.bookmarks
+   */
   {
     namespace: "bookmarks",
     types: [],
@@ -428,7 +585,7 @@
         parameters: [
           {type: "integer", name: "id", minimum: 0},
           {
-            type: "Object",
+            type: "object",
             name: "bookmark",
           }
         ]
@@ -440,7 +597,7 @@
         parameters: [
           {type: "integer", name: "id", minimum: 0},
           {
-            type: "Object",
+            type: "object",
             name: "RemoveInfo",
           }
         ]
@@ -452,7 +609,7 @@
         parameters: [
           {type: "integer", name: "id", minimum: 0},
           {
-            type: "Object",
+            type: "object",
             name: "ChangeInfo",
           }
         ]
@@ -464,7 +621,7 @@
         parameters: [
           {type: "integer", name: "id", minimum: 0},
           {
-            type: "Object",
+            type: "object",
             name: "MoveInfo",
           }
         ]
@@ -476,7 +633,7 @@
         parameters: [
           {type: "integer", name: "id", minimum: 0},
           {
-            type: "Object",
+            type: "object",
             name: "childIds",
           }
         ]
diff --git a/chrome/common/extensions/api/tabs.json b/chrome/common/extensions/api/tabs.json
deleted file mode 100755
index e09f105..0000000
--- a/chrome/common/extensions/api/tabs.json
+++ /dev/null
@@ -1,50 +0,0 @@
-{
-  "namespace": "chrome.tabs",
-  "types": [],
-  "functions": [
-    {
-      "name": "getLanguage",
-      "description": "Attempts to determine the language of the content of the tab with id <var>tabId</var>",
-      "parameters": [
-        { 
-          "name": "tabId",
-          "description": "The id of the tab whose contents should be evaluated for it's source language",
-          "type": "integer",
-          "minimum": 0,
-          "optional": true
-        },
-        { 
-          "name": "callback",
-          "description": "Function to callback upon completion.",
-          "type": "function",
-          "optional": true
-        }
-      ],
-      "callbackParameters" : [
-        {
-          "name": "result",
-          "type": "string",
-          "description": "The language of the content found in specified tab."
-        }
-      ]
-    }
-  ],
-  "events": [
-    {
-      "name": "onMoved",
-      "description": "Sent whenever a tab is moved.",
-      "parameters": [
-        {
-          "name": "tabId",
-          "type": "integer",
-          "description": "The id of the tab that was moved."
-        },
-        {
-          "name": "TabMoveDetails",
-          "type": "object",
-          "description": "Properties describing the tab move event."
-        }
-      ]
-    }
-  ]
-}
\ No newline at end of file
diff --git a/chrome/common/extensions/docs/css/ApiRefStyles.css b/chrome/common/extensions/docs/css/ApiRefStyles.css
index 2626359..37bd248 100755
--- a/chrome/common/extensions/docs/css/ApiRefStyles.css
+++ b/chrome/common/extensions/docs/css/ApiRefStyles.css
@@ -1,12 +1,12 @@
+.todo {
+  color: red;
+}
+
 body {
   font-family:Arial, Helvetica, sans-serif;
   font-size: 13px;
 }
 
-.todo {
-  color: red;
-}
-
 h2,h3 {
   margin-top: 2em;
 }
@@ -88,4 +88,60 @@ p#classSummary {
 
 .hidden {
   display: none;
-}
\ No newline at end of file
+}
+
+#container {
+  height:auto !important;
+  margin:0;
+  max-width:1160px;
+  min-height:100%;
+  padding:0;
+  position:relative;
+}
+
+#pageHeader {
+  margin:9px 0 12px;
+  padding:7px 0 0;
+}
+
+#pageTitle {
+}
+
+#pageContent {
+}
+
+#leftNav {
+  clear:left;
+  padding:0.5em 0 140px !important;
+  display:block;
+  float:left;
+  margin:0;
+  width:171px;
+}
+
+#leftNav ul {
+  line-height:120%;
+  margin:0;
+  padding:0.6em 0 0;
+}
+
+#leftNav ul li {
+  list-style-image:none;
+  list-style-position:outside;
+  list-style-type:none;
+  margin:0;
+  padding:0.2em 0 0.2em 1em;
+}
+
+#mainColumn {
+  border-left:3px solid #E5ECF9;
+  padding-left:24px;
+  display:block;
+  float:none;
+  margin:0 0 0 171px;
+  position:relative;
+  width:auto;
+}
+
+#pageFooter {
+}
diff --git a/chrome/common/extensions/docs/js/api_page_generator.js b/chrome/common/extensions/docs/js/api_page_generator.js
index 01ff9e2d..dcef86f 100755
--- a/chrome/common/extensions/docs/js/api_page_generator.js
+++ b/chrome/common/extensions/docs/js/api_page_generator.js
@@ -32,6 +32,12 @@ Array.prototype.each = function(f) {
   }
 }
 
+Object.prototype.extends = function(obj) {
+  for (var k in obj) {
+    this[k] = obj[k];
+  }
+}
+
 // name of the api this reference page is describing. i.e. "bookmarks", "tabs".
 var apiName;
 
@@ -100,15 +106,21 @@ function fetchContent(url, onSuccess) {
  * <body>.
  * This uses the root <html> element (the entire document) as the template.
  */
-function renderTemplate(schema) {
+function renderTemplate(schemaContent) {
   var apiDefinition;
+  var schema = JSON.parse(schemaContent);
   
-  JSON.parse(schema).each(function(module) {
+  schema.each(function(module) {
     if (module.namespace == apiName)
       apiDefinition = module;
   });
   
-  preprocessApi(apiDefinition);
+  types = {};
+  apiDefinition.types.each(function(t) {
+    types[t.id] = t;
+  });
+  
+  preprocessApi(apiDefinition, schema, types);
 
   // Render to template
   var input = new JsEvalContext(apiDefinition);
@@ -120,36 +132,91 @@ function renderTemplate(schema) {
 }
 
 /**
- * Augment the |schema| with additional values that are required by the
- * template.
+ * Augment the |module| with additional values that are required by the
+ * template. |schema| is the full schema (including all modules). |types| is an
+ * array of typeId -> typeSchema.
  */
-function preprocessApi(schema) {
-  schema.functions.each(function(f) {
-    f.fullName = "chrome." + schema.namespace + "." + f.name;
-    assignTypeNames(f);
+function preprocessApi(module, schema, types) {
+  module.functions.each(function(f) {
+    f.fullName = "chrome." + module.namespace + "." + f.name;
+    linkTypeReferences(f.parameters, types);
+    assignTypeNames(f.parameters);
 
     // Look for a callback that defines parameters.
     if (f.parameters.length > 0) {
       var lastParam = f.parameters[f.parameters.length - 1];
       if (lastParam.type == "function" && lastParam.parameters) {
-        assignTypeNames(lastParam);        
+        linkTypeReferences(lastParam.parameters, types);
+        assignTypeNames(lastParam.parameters);        
         f.callbackParameters = lastParam.parameters;
         f.callbackSignature = generateSignatureString(lastParam.parameters);
+        f.callbackParameters.each(function(p) {
+          addPropertyListIfObject(p);
+        });
       }
     }
-  });
     
-  schema.events.each(function(e) {
-    assignTypeNames(e);    
+    // Setup any type: "object" pameters to have an array of params (rather than 
+    // named properties).
+    f.parameters.each(function(param) {
+      addPropertyListIfObject(param);
+    });
+  });
+  
+  module.events.each(function(e) {
+    linkTypeReferences(e.parameters, types);
+    assignTypeNames(e.parameters);    
     e.callSignature = generateSignatureString(e.parameters);
+    e.parameters.each(function(p) {
+      addPropertyListIfObject(p);
+    });
   });
+
+  // Add a list of modules for the master TOC.
+  module.apiModules = [];
+  schema.each(function(s) {
+    var m = {};
+    m.module = s.namespace;
+    m.name = s.namespace.substring(0, 1).toUpperCase() +
+             s.namespace.substring(1);
+    module.apiModules.push(m);
+  });
+  module.apiModules.sort(function(a, b) { return a.name > b.name; }); 
+}
+
+/*
+ * For function, callback and event parameters, we want to document the
+ * properties of any "object" type. This takes an param, and if it is an
+ * "object" type, creates a "_parameterList" property in the form as
+ * |parameters| list used by the template.
+ */
+function addPropertyListIfObject(object) {
+  if (object.type != "object" || !object.properties)
+    return;
+
+  var propertyList = [];
+  for (var p in object.properties) {
+    var prop = object.properties[p];
+    prop.name = p;
+    propertyList.push(prop);
+  }
+  assignTypeNames(propertyList);
+  object._propertyList = propertyList;
 }
 
+function linkTypeReferences(parameters, types) {
+  parameters.each(function(p) {
+    if (p.$ref) {
+      p.extends(types[p.$ref]);
+    }
+  });
+} 
+
 /**
- * Assigns a typeName(param) to each of the parameters of |f|.
+ * Assigns a typeName(param) to each of the |parameters|.
  */
-function assignTypeNames(f) {
-  f.parameters.each(function(p) {
+function assignTypeNames(parameters) {
+  parameters.each(function(p) {
     p.typeName = typeName(p);
   });
 }
@@ -158,9 +225,6 @@ function assignTypeNames(f) {
  * Generates a short text summary of the |schema| type
  */
 function typeName(schema) {
-  if (schema.$ref)
-    return schema.$ref;
-
   if (schema.choice) {
     var typeNames = [];
     schema.choice.each(function(c) {
diff --git a/chrome/common/extensions/docs/template/api_template.html b/chrome/common/extensions/docs/template/api_template.html
index 0aa613d..fb96a77 100755
--- a/chrome/common/extensions/docs/template/api_template.html
+++ b/chrome/common/extensions/docs/template/api_template.html
@@ -1,168 +1,273 @@
-    <!-- BREADCRUMB -->
-    <!-- TODO: Fix these hrefs -->
-    <div id="breadcrumbs"><a href="../index.html">Chrome Extensions</a> &gt;
-    <a href="./index.html">Reference</a> &gt;
-    <a href="chrome-api-index.html">chrome.* API</a></div>
+  <div id="container">
+  <a name="top"> </a>
 
     <!-- API HEADER -->
-    <h1 jscontent="namespace">chrome.apiname</h1>
-
-    <!-- TABLE OF CONTENTS -->
-    <div id="toc">
-      <p>Contents</p>
-      <ol>
-        <li>
-          <a href="#overview">Description</a>
+    <div id="pageHeader">
+      <!-- BREADCRUMB -->
+      <!-- TODO: Fix these hrefs -->
+      <div id="breadcrumbs">
+        <a href="../index.html">Chrome Extensions</a> &gt;
+        <a href="./index.html">Reference</a> &gt;
+        <a href="chrome-api-index.html">chrome.* API</a>
+      </div>
+      <div id="pageTitle">
+        <h1 jscontent="namespace">chrome.apiname</h1>
+      </div>
+    </div> <!-- /pageHeader -->
+          
+    <div id="pageContent"> 
+      <!-- SIDENAV -->
+      <div id="leftNav">
+        <ul>
+          <li> Overview </li>
+          <li> Programmer's Guide
+            <ul>
+              <li> Getting Started </li>
+              <li> ... </li>
+            </ul>
+          </li>
+          <li> Reference 
+            <ul>
+              <li> chrome.* APIs
+                <ul>
+                  <li jsselect="apiModules">
+                    <a jscontent="name" jsvalues=".href:module + '.html'">Foo</a>
+                  </li>
+                </ul>
+              </li>
+            </ul>
+          </li>
+        </ul>
+      </div>
+    
+      <div id="mainColumn">
+        <!-- TABLE OF CONTENTS -->
+        <div id="toc">
+          <p>Contents</p>
           <ol>
-            <li><a href="#overview-properties">Properties</a></li>
-            <li><a href="#overview-examples">Examples</a></li>
-          </ol>
-        </li>
-        <li>
-          <a href="#methods">Methods</a>    
-          <ol>
-            <li jsselect="functions">
-              <a jscontent="name"
-                 jsvalues=".href:'#method-' + name"
-                 href="#method-anchor">methodName</a>
+            <li>
+              <a href="#overview">Description</a>
+              <ol>
+                <li><a href="#overview-properties">Properties</a></li>
+                <li><a href="#overview-examples">Examples</a></li>
+              </ol>
             </li>
-          </ol>
-        </li>
-        <li>
-          <a href="#events">Events</a>
-          <ol>
-            <li jsselect="events">
-              <a jscontent="name"
-                 jsvalues=".href:'#event-' + name"
-                 href="#event-anchor">eventName</a>
+            <li>
+              <a href="#methods">Methods</a>    
+              <ol>
+                <li jsselect="functions">
+                  <a jscontent="name"
+                     jsvalues=".href:'#method-' + name"
+                     href="#method-anchor">methodName</a>
+                </li>
+              </ol>
+            </li>
+            <li>
+              <a href="#events">Events</a>
+              <ol>
+                <li jsselect="events">
+                  <a jscontent="name"
+                     jsvalues=".href:'#event-' + name"
+                     href="#event-anchor">eventName</a>
+                </li>
+              </ol>
+            </li>
+            <!-- TODO: What do we do about structs/types? -->
+            <li>
+              <a href="#structs">TODO: Structs</a>
+              <ol>
+                <li><a href="#struct-BookmarkTreeNode"></a></li>
+              </ol>
             </li>
           </ol>
-        </li>
-        <!-- TODO: What do we do about structs/types? -->
-        <li>
-          <a href="#structs">TODO: Structs</a>
-          <ol>
-            <li><a href="#struct-BookmarkTreeNode"></a></li>
-          </ol>
-        </li>
-      </ol>
-      [PENDING: links to all h2s and h3s should go here -- would it be possible
-      to link to overview h3s, as well? if so, how should we create their
-      anchor/id values?]
-    </div>  
-    <!-- /TABLE OF CONTENTS -->
-
-
-    <!-- OVERVIEW PLACEHOLDER -- THIS GET REPLACED AUTHORED CONTENT -->
-    <div id="overview"></div>
-
-
-    <!-- METHODS -->
-    <div class="apiGroup" id="methods">
-      <a name="#methods"></a>
-      <h2>Methods</h2>
-
-      <!-- iterates over all functions -->
-      <div class="apiItem" jsselect="functions">
-        <a jsvalues=".name:'method-' + name"></a> <!-- method-anchor -->
-        <h3 jscontent="name">method name</h3>
-
-        <div class="summary">void
-            <!-- Note: intentionally longer 80 columns -->
-            <span jscontent="fullName">chrome.module.methodName</span>(<span jsselect="parameters" jsvalues="class:optional ? 'optional' : ''"><span jsdisplay="$index">, </span><span jscontent="typeName"></span>
-                <var><span jscontent="name"></span></var></span>)</div>
-
-        <div class="description">
-          <p class="todo" jsdisplay="!description">Undocumented.</p>
-          <p jsdisplay="description" jsvalues=".innerHTML:description">
-            A description from the json schema def of the function goes here.
-          </p>
-
-          <!-- PARAMETERS -->
-          <h4>Parameters</h4>
-          <dl>
-            <div jsselect="parameters">
-              <dt>
-                <!-- Note: intentionally longer 80 columns -->
-                <var jscontent="name">paramName</var><em>
-                    (<span class="optional" jsdisplay="optional">optional </span><span jscontent="typeName">paramType</span>)</em>
-              </dt>
-              <dd class="todo" jsdisplay="!$this.description">Undocumented.</dd>
-              <dd jsdisplay="$this.description" jsvalues=".innerHTML:$this.description">
-                Description of this parameter from the json schema.
-              </dd>
-            </div>
-          </dl>
-
-          <!-- CALLBACK -->	
-          <div jsdisplay="callbackParameters">
-            <h4>Callback function</h4>
-            <p>
-              If you specify the <em>callback</em> parameter,
-              it should specify a function that looks like this:
-            </p>
-            
-            <!-- Note: intentionally longer 80 columns -->
-            <pre>function(<span jscontent="callbackSignature">Type param1, Type param2</span>) <span class="subdued">{...}</span>);</pre>
-            <dl>
-              <div jsselect="callbackParameters">
-                <dt>
-                  <!-- Note: intentionally longer 80 columns -->
-                  <var jscontent="name">paramName</var><em>
-                      (<span jscontent="typeName">paramType</span>)</em>
-                </dt>
-                <dd class="todo" jsdisplay="!$this.description">Undocumented.</dd>
-                <dd jsdisplay="$this.description" jsvalues=".innerHTML:$this.description">
-                  Description of this parameter from the json schema.
-                </dd>
-              </div>
-            </dl>
-          </div>
+          [PENDING: links to all h2s and h3s should go here -- would it be possible
+          to link to overview h3s, as well? if so, how should we create their
+          anchor/id values?]
+        </div>  
+        <!-- /TABLE OF CONTENTS -->
 
-        </div> <!-- /description -->
 
-      </div>  <!-- /apiItem -->
+        <!-- OVERVIEW PLACEHOLDER -- THIS GET REPLACED AUTHORED CONTENT -->
+        <div id="overview"></div>
 
-    </div>  <!-- /apiGroup -->
 
-    <!-- EVENTS -->
-    <div class="apiGroup" id="events">
-      <a name="#events"></a>
-      <h2 id="events">Events</h2>
+        <!-- METHODS -->
+        <div class="apiGroup" id="methods">
+          <a name="#methods"></a>
+          <h2>Methods</h2>
 
-      <!-- iterates over all events -->
-      <div jsselect="events" class="apiItem" jsselect="functions">
-        <a jsvalues=".name:'event-' + name"></a>
-        <h3 jscontent="name">event name</h3>
+          <!-- iterates over all functions -->
+          <div class="apiItem" jsselect="functions">
+            <a jsvalues=".name:'method-' + name"></a> <!-- method-anchor -->
+            <h3 jscontent="name">method name</h3>
 
-        <div class="summary">
-          <!-- Note: intentionally longer 80 columns -->
-          <span class="subdued">chrome.bookmarks.</span><span jscontent="name">onEvent</span><span class="subdued">.addListener</span>(function(<span jscontent="callSignature">Type param1, Type param2</span>) <span class="subdued">{...}</span>);
-        </div>
+            <div class="summary">void
+                <!-- Note: intentionally longer 80 columns -->
+                <span jscontent="fullName">chrome.module.methodName</span>(<span jsselect="parameters" jsvalues="class:optional ? 'optional' : ''"><span jsdisplay="$index">, </span><span jscontent="typeName"></span>
+                    <var><span jscontent="name"></span></var></span>)</div>
+
+            <div class="description">
+              <p class="todo" jsdisplay="!description">Undocumented.</p>
+              <p jsdisplay="description" jsvalues=".innerHTML:description">
+                A description from the json schema def of the function goes here.
+              </p>
 
-        <div class="description">
-          <p class="todo" jsdisplay="!description">Undocumented.</p>
-          <p jsdisplay="description" jsvalues=".innerHTML:description">
-            A description from the json schema def of the event goes here.
-          </p>
+              <!-- PARAMETERS -->
+              <h4>Parameters</h4>
+              <dl>
+                <div jsselect="parameters">
+                  <dt>
+                    <!-- Note: intentionally longer 80 columns -->
+                    <var jscontent="name">paramName</var><em>
+                        (<span class="optional" jsdisplay="optional">optional </span><span jscontent="typeName">paramType</span>)</em>
+                  </dt>
+                  <dd class="todo" jsdisplay="!$this.description">
+                    Undocumented.
+                  </dd>
+                  <dd jsdisplay="$this.description"
+                      jsvalues=".innerHTML:$this.description">
+                    Description of this parameter from the json schema.
+                  </dd>
+                  
+                  <!-- OBJECT PROPERTIES -->
+                  <dd jsdisplay="_propertyList">
+                    <dl>
+                      <div jsselect="_propertyList">
+                        <dt>
+                          <!-- Note: intentionally longer 80 columns -->
+                          <var jscontent="name">paramName</var><em>
+                              (<span class="optional" jsdisplay="optional">optional </span><span jscontent="typeName">paramType</span>)</em>
+                        </dt>
+                        <dd class="todo" jsdisplay="!$this.description">
+                          Undocumented.
+                        </dd>
+                        <dd jsdisplay="$this.description"
+                            jsvalues=".innerHTML:$this.description">
+                          Description of this parameter from the json schema.
+                        </dd>
+                      </div>
+                    </dl>
+                  </dd>
+                </div>
+              </dl>
 
-          <!-- PARAMETERS -->
-          <h4>Parameters</h4>
-          <dl>
-            <div jsselect="parameters">
-              <dt>
+              <!-- CALLBACK -->	
+              <div jsdisplay="callbackParameters">
+                <h4>Callback function</h4>
+                <p>
+                  If you specify the <em>callback</em> parameter,
+                  it should specify a function that looks like this:
+                </p>
+                
                 <!-- Note: intentionally longer 80 columns -->
-                <var jscontent="name">paramName</var><em> (<span jscontent="typeName">paramType</span>)</em>
-              </dt>
-              <dd class="todo" jsdisplay="!$this.description">Undocumented.</dd>
-              <dd jsdisplay="$this.description" jsvalues=".innerHTML:$this.description">
-                Description of this parameter from the json schema.
-              </dd>
+                <pre>function(<span jscontent="callbackSignature">Type param1, Type param2</span>) <span class="subdued">{...}</span>);</pre>
+                <dl>
+                  <div jsselect="callbackParameters">
+                    <dt>
+                      <!-- Note: intentionally longer 80 columns -->
+                      <var jscontent="name">paramName</var><em>
+                          (<span jscontent="typeName">paramType</span>)</em>
+                    </dt>
+                    <dd class="todo" jsdisplay="!$this.description">
+                      Undocumented.
+                    </dd>
+                    <dd jsdisplay="$this.description"
+                        jsvalues=".innerHTML:$this.description">
+                      Description of this parameter from the json schema.
+                    </dd>
+                    <!-- OBJECT PROPERTIES -->
+                    <dd jsdisplay="_propertyList">
+                      <dl>
+                        <div jsselect="_propertyList">
+                          <dt>
+                            <!-- Note: intentionally longer 80 columns -->
+                            <var jscontent="name">paramName</var><em>
+                                (<span class="optional" jsdisplay="optional">optional </span><span jscontent="typeName">paramType</span>)</em>
+                          </dt>
+                          <dd class="todo" jsdisplay="!$this.description">
+                            Undocumented.
+                          </dd>
+                          <dd jsdisplay="$this.description"
+                              jsvalues=".innerHTML:$this.description">
+                            Description of this parameter from the json schema.
+                          </dd>
+                        </div>
+                      </dl>
+                    </dd>
+                  </div>
+                </dl>
+              </div>
+
+            </div> <!-- /description -->
+
+          </div>  <!-- /apiItem -->
+
+        </div>  <!-- /apiGroup -->
+
+        <!-- EVENTS -->
+        <div class="apiGroup" id="events">
+          <a name="#events"></a>
+          <h2 id="events">Events</h2>
+
+          <!-- iterates over all events -->
+          <div jsselect="events" class="apiItem" jsselect="functions">
+            <a jsvalues=".name:'event-' + name"></a>
+            <h3 jscontent="name">event name</h3>
+
+            <div class="summary">
+              <!-- Note: intentionally longer 80 columns -->
+              <span class="subdued">chrome.bookmarks.</span><span jscontent="name">onEvent</span><span class="subdued">.addListener</span>(function(<span jscontent="callSignature">Type param1, Type param2</span>) <span class="subdued">{...}</span>);
             </div>
-          </dl>
 
-        </div> <!-- /decription -->
+            <div class="description">
+              <p class="todo" jsdisplay="!description">Undocumented.</p>
+              <p jsdisplay="description" jsvalues=".innerHTML:description">
+                A description from the json schema def of the event goes here.
+              </p>
+
+              <!-- PARAMETERS -->
+              <h4>Parameters</h4>
+              <dl>
+                <div jsselect="parameters">
+                  <dt>
+                    <!-- Note: intentionally longer 80 columns -->
+                    <var jscontent="name">paramName</var><em> (<span jscontent="typeName">paramType</span>)</em>
+                  </dt>
+                  <dd class="todo" jsdisplay="!$this.description">Undocumented.</dd>
+                  <dd jsdisplay="$this.description" jsvalues=".innerHTML:$this.description">
+                    Description of this parameter from the json schema.
+                  </dd>
+                  
+                  <!-- OBJECT PROPERTIES -->
+                  <dd jsdisplay="_propertyList">
+                    <dl>
+                      <div jsselect="_propertyList">
+                        <dt>
+                          <!-- Note: intentionally longer 80 columns -->
+                          <var jscontent="name">paramName</var><em>
+                              (<span class="optional" jsdisplay="optional">optional </span><span jscontent="typeName">paramType</span>)</em>
+                        </dt>
+                        <dd class="todo" jsdisplay="!$this.description">
+                          Undocumented.
+                        </dd>
+                        <dd jsdisplay="$this.description"
+                            jsvalues=".innerHTML:$this.description">
+                          Description of this parameter from the json schema.
+                        </dd>
+                      </div>
+                    </dl>
+                  </dd>
+                </div>
+              </dl>
+
+            </div> <!-- /decription -->
 
-      </div> <!-- /apiItem -->
+          </div> <!-- /apiItem -->
 
-    </div> <!-- /apiGroup -->
\ No newline at end of file
+        </div> <!-- /apiGroup -->
+      </div> <!-- /mainColumn -->
+    </div> <!-- /pageContent -->
+    <div id="pageFooter" -->
+      TBD: copyright/license goes here
+    </div> <!-- /pageFooter -->
+  </div> <!-- /container -->
\ No newline at end of file