8 files changed, 229 insertions, 73 deletions
diff --git a/chrome/common/common_resources.grd b/chrome/common/common_resources.grd
index 5ea8f3c..5e90f50 100644
--- a/chrome/common/common_resources.grd
+++ b/chrome/common/common_resources.grd
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!-- This comment is only here because changes to resources are not picked up
-without changes to the corresponding grd file. rw -->
+without changes to the corresponding grd file. rw2 -->
 <grit latest_public_release="0" current_release="1">
   <outputs>
     <output filename="grit/common_resources.h" type="rc_header">
diff --git a/chrome/common/extensions/api/extension_api.json b/chrome/common/extensions/api/extension_api.json
index 8e8aa52..a128c88 100755
--- a/chrome/common/extensions/api/extension_api.json
+++ b/chrome/common/extensions/api/extension_api.json
@@ -68,6 +68,33 @@
 
 [
   /**
+   * chrome.self
+   */
+  {
+    namespace: "self",
+    types: [
+      {
+        id: "HTMLWindow",
+        type: "object"
+      }
+    ],
+    functions: [
+      {
+        name: "getViews",
+        type: "function",
+        description: "Returns an array of the global JavaScript objects for each of the views running inside the current extension. This includes toolstrips, background pages, and tabs.",
+        parameters: [],
+        returns: {
+          type: "array",
+          description: "Array of HTMLWindow objects",
+          items: { $ref: "HTMLWindow" }
+        }
+      },
+    ],
+    events: []
+  },
+  
+  /**
    * chrome.windows
    */
   {
@@ -191,19 +218,28 @@
   {
     namespace: "tabs",
     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}
+      {
+        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}
+        }
+      },
+      {
+        id: "Port",
+        type: "object",
+        properties: {
+          name: {type: "string"},
+          onDisconnect: {type: "object"},
+          onMessage: {type: "object"}
+        }
       }
-    }
     ],
     functions: [
       {
@@ -222,6 +258,19 @@
         ]
       },
       {
+        name: "connect",
+        type: "function",
+        description: "",
+        parameters: [
+          {type: "integer", name: "tabId", optional: true, minimum: 0},
+          {type: "string", name: "name", optional: true}
+        ],
+        returns: {
+          name: "Port",
+          $ref: "Port"
+        }
+      },
+      {
         name: "getSelected",
         type: "function",
         description: "",
diff --git a/chrome/common/extensions/docs/js/api_page_generator.js b/chrome/common/extensions/docs/js/api_page_generator.js
index 4c36b3e..6567378 100755
--- a/chrome/common/extensions/docs/js/api_page_generator.js
+++ b/chrome/common/extensions/docs/js/api_page_generator.js
@@ -164,6 +164,13 @@ function preprocessApi(module, schema, types) {
     f.parameters.each(function(param) {
       addPropertyListIfObject(param);
     });
+    
+    // Setup return typeName & _propertyList, if any.
+    if (f.returns) {
+      linkTypeReference(f.returns, types);
+      f.returns.typeName = typeName(f.returns);
+      addPropertyListIfObject(f.returns);
+    }
   });
   
   module.events.each(function(e) {
@@ -209,11 +216,15 @@ function addPropertyListIfObject(object) {
 
 function linkTypeReferences(parameters, types) {
   parameters.each(function(p) {
-    if (p.$ref) {
-      extend(p, types[p.$ref]);
-    }
+    linkTypeReference(p, types);
   });
-} 
+}
+
+function linkTypeReference(schema, types) {
+  if (schema.$ref) {
+    extend(schema, types[schema.$ref]);
+  }
+}
 
 /**
  * Assigns a typeName(param) to each of the |parameters|.
diff --git a/chrome/common/extensions/docs/reference/self.html b/chrome/common/extensions/docs/reference/self.html
new file mode 100755
index 0000000..c05e097
--- /dev/null
+++ b/chrome/common/extensions/docs/reference/self.html
@@ -0,0 +1,33 @@
+<!DOCTYPE html>
+<!-- This page is a placeholder for generated extensions api doc. Note:
+    1) The <head> information in this page is significant, should be uniform
+       across api docs and should be edited only with knowledge of the
+       templating mechanism.
+    2) The <body> tag *must* retain id="body"
+    3) All <body>.innerHTML is genereated as an rendering step. If viewed in a
+       browser, it will be re-generated from the template, json schema and
+       authored overview content.
+    4) The <body>.innerHTML is also generated by an offline step so that this
+       page may easily be indexed by search engines.
+       
+    TODO(rafaelw): Abstract this into a "pageshell" that becomes the single
+    version of page template shell and the "instance" pages (bookmarks.html,
+    etc...) can be generated with a build step.
+-->
+<!-- <html> must retain id="template -->
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <!-- <head> data is significant and loads the needed libraries and styles -->
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+    <title jscontent="namespace">chrome.apiname</title>
+    <link href="../css/ApiRefStyles.css" rel="stylesheet" type="text/css">
+    <script type="text/javascript"
+            src="../../../../third_party/jstemplate/jstemplate_compiled.js">
+    </script>
+    <script type="text/javascript" src="../js/api_page_generator.js"></script>
+  </head>
+  <!-- <body> content is completely generated. Do not edit, as it will be
+      and rewritten. -->
+  <body class="hidden">
+  </body>
+</html>
diff --git a/chrome/common/extensions/docs/reference/self_overview.html b/chrome/common/extensions/docs/reference/self_overview.html
new file mode 100755
index 0000000..997b579
--- /dev/null
+++ b/chrome/common/extensions/docs/reference/self_overview.html
@@ -0,0 +1,5 @@
+<!-- BEGIN AUTHORED CONTENT -->
+<p class="todo"> 
+[PENDING: API Module Overview Goes Here]
+</p>
+<!-- END AUTHORED CONTENT -->
diff --git a/chrome/common/extensions/docs/template/api_template.html b/chrome/common/extensions/docs/template/api_template.html
index 3bdc176..ed0afd3 100755
--- a/chrome/common/extensions/docs/template/api_template.html
+++ b/chrome/common/extensions/docs/template/api_template.html
@@ -113,7 +113,7 @@
             <a jsvalues=".name:'method-' + name"></a> <!-- method-anchor -->
             <h3 jscontent="name">method name</h3>
 
-            <div class="summary">void
+            <div class="summary"><span jsdisplay="returns" jscontent="returns.typeName">void</span>
                 <!-- 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>
@@ -162,6 +162,45 @@
                   </dd>
                 </div>
               </dl>
+              
+              <!-- RETURNS -->
+              <h4 jsdisplay="returns">Returns</h4>
+              <dl>
+                <div jsselect="returns">
+                  <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>
 
               <!-- CALLBACK -->	
               <div jsdisplay="callbackParameters">
diff --git a/chrome/renderer/renderer_resources.grd b/chrome/renderer/renderer_resources.grd
index bdba06d..5e05578 100644
--- a/chrome/renderer/renderer_resources.grd
+++ b/chrome/renderer/renderer_resources.grd
@@ -1,6 +1,6 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <!-- This comment is only here because changes to resources are not picked up
-without changes to the corresponding grd file. mp1 -->
+without changes to the corresponding grd file. rw3 -->
 <grit latest_public_release="0" current_release="1">
   <outputs>
     <output filename="grit/renderer_resources.h" type="rc_header">
diff --git a/chrome/renderer/resources/extension_process_bindings.js b/chrome/renderer/resources/extension_process_bindings.js
index fb57923..7218d03 100644
--- a/chrome/renderer/resources/extension_process_bindings.js
+++ b/chrome/renderer/resources/extension_process_bindings.js
@@ -80,19 +80,46 @@ var chrome = chrome || {};
     }
   };
 
+  function prepareRequest(args, argSchemas) {
+    var request = {};
+    var argCount = args.length;
+    
+    // Look for callback param.
+    if (argSchemas.length > 0 &&
+        args.length == argSchemas.length &&
+        argSchemas[argSchemas.length - 1].type == "function") {
+      request.callback = args[argSchemas.length - 1];
+      --argCount;
+    }
+    
+    // Calls with one argument expect singular argument. Calls with multiple
+    // expect a list.
+    if (argCount == 1)
+      request.args = args[0];
+    if (argCount > 1) {
+      request.args = [];
+      for (var k = 0; k < argCount; k++) {
+        request.args[k] = args[k];
+      }
+    }
+    
+    return request;
+  }
+
   // Send an API request and optionally register a callback.
-  function sendRequest(functionName, args, callback) {
+  function sendRequest(functionName, args, argSchemas) {
+    var request = prepareRequest(args, argSchemas);
     // JSON.stringify doesn't support a root object which is undefined.
-    if (args === undefined)
-      args = null;
-    var sargs = JSON.stringify(args);
+    if (request.args === undefined)
+      request.args = null;
+    var sargs = JSON.stringify(request.args);
     var requestId = GetNextRequestId();
     var hasCallback = false;
-    if (callback) {
+    if (request.callback) {
       hasCallback = true;
-      callbacks[requestId] = callback;
+      callbacks[requestId] = request.callback;
     }
-    StartRequest(functionName, sargs, requestId, hasCallback);
+    return StartRequest(functionName, sargs, requestId, hasCallback);
   }
   
   // Read api definitions and setup api functions in the chrome namespace.
@@ -102,6 +129,11 @@ var chrome = chrome || {};
   // TOOD(rafaelw): Consider providing some convenient override points
   //   for api functions that wish to insert themselves into the call. 
   var apiDefinitions = JSON.parse(GetExtensionAPIDefinition());
+  
+  // |apiFunctions| is a hash of name -> object that stores the 
+  // name & definition of the apiFunction. Custom handling of api functions
+  // is implemented by adding a "handleRequest" function to the object.
+  var apiFunctions = {};
 
   // Using forEach for convenience, and to bind |module|s & |apiDefs|s via
   // closures.
@@ -111,51 +143,43 @@ var chrome = chrome || {};
     }
   }
 
+  function bind(obj, func) {
+    return function() {
+      return func.apply(obj, arguments);
+    };
+  }
+
   forEach(apiDefinitions, function(apiDef) {
     var module = {};
     chrome[apiDef.namespace] = module;
     
     // Setup Functions.
-    forEach(apiDef.functions, function(functionDef) {
-      var paramSchemas = functionDef.parameters;
-      
-      module[functionDef.name] = function() {
-        validate(arguments, paramSchemas);
-        
-        var functionName = apiDef.namespace + "." + functionDef.name;
-        var args = null;
-        var callback = null;
-        var argCount = arguments.length;
-        
-        // Look for callback param.
-        if (paramSchemas.length > 0 &&
-            arguments.length == paramSchemas.length &&
-            paramSchemas[paramSchemas.length - 1].type == "function") {
-          callback = arguments[paramSchemas.length - 1];
-          --argCount;
-        }
-        
-        // Calls with one argument expect singular argument. Calls with multiple
-        // expect a list.
-        if (argCount == 1)
-          args = arguments[0];
-        if (argCount > 1) {
-          args = [];
-          for (var k = 0; k < argCount; k++) {
-            args[k] = arguments[k];
-          }
-        }
+    if (apiDef.functions) {
+      forEach(apiDef.functions, function(functionDef) {
+        var apiFunction = {};      
+        apiFunction.definition = functionDef;
+        apiFunction.name = apiDef.namespace + "." + functionDef.name;;
+        apiFunctions[apiFunction.name] = apiFunction;
         
-        // Make the request.
-        sendRequest(functionName, args, callback);        
-      }
-    });
+        module[functionDef.name] = bind(apiFunction, function() {
+          validate(arguments, this.definition.parameters);
+    
+          if (this.handleRequest)
+            return this.handleRequest.apply(this, arguments);
+          else 
+            return sendRequest(this.name, arguments,
+                this.definition.parameters);        
+        });
+      });
+    }
     
     // Setup Events
-    forEach(apiDef.events, function(eventDef) {
-      var eventName = apiDef.namespace + "." + eventDef.name;
-      module[eventDef.name] = new chrome.Event(eventName);
-    });
+    if (apiDef.events) {
+      forEach(apiDef.events, function(eventDef) {
+        var eventName = apiDef.namespace + "." + eventDef.name;
+        module[eventDef.name] = new chrome.Event(eventName);
+      });
+    }
   });
 
   // --- Setup additional api's not currently handled in common/extensions/api
@@ -172,16 +196,10 @@ var chrome = chrome || {};
   }
 
   // Tabs connect()
-  chrome.tabs.connect = function(tabId, opt_name) {
-    validate(arguments, arguments.callee.params);
+  apiFunctions["tabs.connect"].handleRequest = function(tabId, opt_name) {
     var portId = OpenChannelToTab(tabId, chrome.extension.id_, opt_name || "");
     return chromeHidden.Port.createPort(portId, opt_name);
-  };
-
-  chrome.tabs.connect.params = [
-    {type: "integer", optional: true, minimum: 0},
-    {type: "string", optional: true}
-  ];
+  }
 
   // chrome.self / chrome.extension.
   chrome.self = chrome.self || {};
@@ -194,8 +212,9 @@ var chrome = chrome || {};
 
     setupPageActionEvents(extensionId);
   });
-
-  chrome.self.getViews = function() {
+  
+  // Self getViews();
+  apiFunctions["self.getViews"].handleRequest = function() {
     return GetViews();
   }
 })();