From 0e9e1dc7b36fbc803e21544493e23e1c319f3f69 Mon Sep 17 00:00:00 2001
From: "kalman@chromium.org"
 <kalman@chromium.org@0039d316-1c4b-4281-b951-d872f2087c98>
Date: Mon, 13 Feb 2012 23:21:44 +0000
Subject: Allow "internal" APIs to be specified in extension API schemas, and
 specify the Declarative API as internal.

BUG=
TEST=browser_tests

Review URL: https://chromiumcodereview.appspot.com/9309114

git-svn-id: svn://svn.chromium.org/chrome/trunk/src@121757 0039d316-1c4b-4281-b951-d872f2087c98
---
 chrome/common/extensions/docs/build/directory.py   |  17 +++++++++----
 .../docs/examples/api/browsingData/basic.zip       | Bin 9077 -> 9255 bytes
 .../extensions/docs/js/api_page_generator.js       |  27 +++++++++------------
 chrome/common/extensions/docs/samples.json         |   3 ++-
 chrome/common/extensions/docs/static/samples.html  |   7 +++---
 .../extensions/docs/template/api_template.html     |   8 +++---
 6 files changed, 33 insertions(+), 29 deletions(-)

(limited to 'chrome/common/extensions/docs')

diff --git a/chrome/common/extensions/docs/build/directory.py b/chrome/common/extensions/docs/build/directory.py
index 53bb521..316e0d6 100644
--- a/chrome/common/extensions/docs/build/directory.py
+++ b/chrome/common/extensions/docs/build/directory.py
@@ -107,7 +107,8 @@ class ApiManifest(object):
           "chrome.tabs.onDetached" : "tabs.html#event-onDetatched"
         }
 
-      If the API namespace is defined "nodoc" then an empty dict is returned.
+      If the API namespace is defined "nodoc" or "internal" then an empty dict
+      is returned.
 
     Raises:
       Exception: If the key supplied is not a member of _MODULE_DOC_KEYS.
@@ -115,14 +116,14 @@ class ApiManifest(object):
     methods = []
     api_dict = {}
     namespace = module['namespace']
-    if module.has_key('nodoc'):
+    if self._disableDocs(module):
       return api_dict
     if key not in self._MODULE_DOC_KEYS:
       raise Exception("key %s must be one of %s" % (key, self._MODULE_DOC_KEYS))
     if module.has_key(key):
       methods.extend(module[key])
     for method in methods:
-      if method.has_key('nodoc'):
+      if self._disableDocs(method):
         continue
       method_name = 'chrome.%s.%s' % (namespace, method['name'])
       hashprefix = 'method'
@@ -136,9 +137,15 @@ class ApiManifest(object):
 
     Returns:
       The namespace """
-    # Exclude modules with a "nodoc" property.
+    # Exclude modules with documentation disabled.
     return set(module['namespace'].encode() for module in self._manifest
-               if "nodoc" not in module)
+               if not self._disableDocs(module))
+
+  def _disableDocs(self, obj):
+    for key in ['nodoc', 'internal']:
+      if key in obj and obj[key]:
+        return True
+    return False
 
   def getDocumentationLinks(self):
     """ Parses the extension API JSON manifest and returns a dict of all
diff --git a/chrome/common/extensions/docs/examples/api/browsingData/basic.zip b/chrome/common/extensions/docs/examples/api/browsingData/basic.zip
index c49c0c5..d1c9cff 100644
Binary files a/chrome/common/extensions/docs/examples/api/browsingData/basic.zip and b/chrome/common/extensions/docs/examples/api/browsingData/basic.zip differ
diff --git a/chrome/common/extensions/docs/js/api_page_generator.js b/chrome/common/extensions/docs/js/api_page_generator.js
index 71ccc11..13f7d85 100644
--- a/chrome/common/extensions/docs/js/api_page_generator.js
+++ b/chrome/common/extensions/docs/js/api_page_generator.js
@@ -260,10 +260,9 @@ function fetchContent(url, onSuccess, onError) {
 function renderTemplate() {
   schema.forEach(function(mod) {
     if (mod.namespace == pageBase) {
-      // Do not render page for modules which are marked as "nodoc": true.
-      if (mod.nodoc) {
+      // Do not render page for modules which have documentation disabled.
+      if (disableDocs(mod))
         return;
-      }
       // This page is an api page. Setup types and apiDefinition.
       module = mod;
       apiModuleName = API_MODULE_PREFIX + module.namespace;
@@ -425,7 +424,8 @@ function selectCurrentPageOnLeftNav() {
 
 function stableAPIs() {
   return schema.filter(function(module) {
-    return !module.nodoc && module.namespace.indexOf('experimental') < 0;
+    return !disableDocs(module) &&
+           module.namespace.indexOf('experimental') < 0;
   }).map(function(module) {
     return module.namespace;
   }).sort();
@@ -433,15 +433,8 @@ function stableAPIs() {
 
 function experimentalAPIs() {
   return schema.filter(function(module) {
-    return !module.nodoc && module.namespace.indexOf('experimental') == 0;
-  }).map(function(module) {
-    return module.namespace;
-  }).sort();
-}
-
-function devtoolsAPIs() {
-  return schema.filter(function(module) {
-    return !module.nodoc && module.namespace.indexOf('devtools.') === 0;
+    return !disableDocs(module) &&
+           module.namespace.indexOf('experimental') == 0;
   }).map(function(module) {
     return module.namespace;
   }).sort();
@@ -603,8 +596,8 @@ function getPropertyListFromObject(object) {
   }
   for (var p in properties) {
     var prop = properties[p];
-    // Do not render properties marked as "nodoc": true.
-    if (prop.nodoc) {
+    // Do not render properties with documentation disabled.
+    if (disableDocs(prop)) {
       continue;
     }
     prop.name = p;
@@ -672,3 +665,7 @@ function sortByName(a, b) {
   }
   return 0;
 }
+
+function disableDocs(obj) {
+  return !!obj.nodoc || !!obj.internal;
+}
diff --git a/chrome/common/extensions/docs/samples.json b/chrome/common/extensions/docs/samples.json
index 189e724..f270885 100644
--- a/chrome/common/extensions/docs/samples.json
+++ b/chrome/common/extensions/docs/samples.json
@@ -68,6 +68,7 @@
     "chrome.experimental.devtools.console.addMessage": "experimental.devtools.console.html#method-addMessage",
     "chrome.experimental.devtools.console.getMessages": "experimental.devtools.console.html#method-getMessages",
     "chrome.experimental.devtools.console.onMessageAdded": "experimental.devtools.console.html#event-onMessageAdded",
+    "chrome.experimental.extension.onInstalled": "experimental.extension.html#event-onInstalled",
     "chrome.experimental.infobars.show": "experimental.infobars.html#method-show",
     "chrome.experimental.speechInput.isRecording": "experimental.speechInput.html#method-isRecording",
     "chrome.experimental.speechInput.onError": "experimental.speechInput.html#event-onError",
@@ -516,7 +517,7 @@
         "popup.html",
         "popup.js"
       ],
-      "source_hash": "20928606eac79b96493a7eae6f71c5210bbddb09",
+      "source_hash": "be5c852d38ee7b7d21483b2d070a1bdebbf6b27c",
       "zip_path": "examples\/api\/browsingData\/basic.zip"
     },
     {
diff --git a/chrome/common/extensions/docs/static/samples.html b/chrome/common/extensions/docs/static/samples.html
index 0ae778c..2cd56a3 100644
--- a/chrome/common/extensions/docs/static/samples.html
+++ b/chrome/common/extensions/docs/static/samples.html
@@ -14,10 +14,9 @@
   pageData.api_mapping = apiMapping;
   pageData.api_modules = [];
   schema.forEach(function(mod) {
-    if (mod.nodoc) {
-      return;
-    }
-    if (mod.namespace.indexOf('experimental') != -1) {
+    if (mod.nodoc ||
+        mod.internal ||
+        mod.namespace.indexOf('experimental') != -1) {
       return;
     }
     pageData.api_modules.push('chrome.' + mod.namespace);
diff --git a/chrome/common/extensions/docs/template/api_template.html b/chrome/common/extensions/docs/template/api_template.html
index d6845f2..ee4afee 100644
--- a/chrome/common/extensions/docs/template/api_template.html
+++ b/chrome/common/extensions/docs/template/api_template.html
@@ -129,7 +129,7 @@
             <a jsvalues=".href:'#' + getAnchorName('global', 'methods', $type)">Methods</a>
             <ol>
               <li jsselect="functions.sort(sortByName)"
-                  jsdisplay="!($this.nodoc)">
+                  jsdisplay="!disableDocs($this)">
                 <a jscontent="name"
                    jsvalues=".href:'#' + getAnchorName('method', name, $type)"
                    href="#method-anchor">methodName</a>
@@ -140,7 +140,7 @@
             <a jsvalues=".href:'#' + getAnchorName('global', 'events', $type)">Events</a>
             <ol>
               <li jsselect="events.sort(sortByName)"
-                  jsdisplay="!($this.nodoc)">
+                  jsdisplay="!disableDocs($this)">
                 <a jscontent="name"
                    jsvalues=".href:'#' + getAnchorName('event', name, $type)"
                    href="#event-anchor">eventName</a>
@@ -382,7 +382,7 @@
 
             <!-- iterates over all functions -->
             <div class="apiItem" jsselect="functions.sort(sortByName)"
-                 jsdisplay="!($this.nodoc)">
+                 jsdisplay="!disableDocs($this)">
               <a jsvalues=".name:getAnchorName('method', name, $scope)"></a> <!-- method-anchor -->
               <h4 jscontent="name">method name</h4>
 
@@ -459,7 +459,7 @@
             <h3 jscontent="$scope ? 'Events of ' + $scope : 'Events'">Events</h3>
             <!-- iterates over all events -->
             <div class="apiItem" jsselect="$this.events.sort(sortByName)"
-                 jsdisplay="!($this.nodoc)">
+                 jsdisplay="!disableDocs($this)">
               <a jsvalues=".name:getAnchorName('event', name, $scope)"></a>
               <h4 jscontent="name">event name</h4>
 
-- 
cgit v1.1