Pull out synchronous extension apis to extensions_api.json, add custom handling for calls

R=aa

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

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

6 files changed, 155 insertions, 18 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">