Extensions Docs Server: Support APIs with properties

Added a template for API properties. I also added templates for the privacy API,
which has properties.

BUG=131095

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

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

15 files changed, 127 insertions, 48 deletions

diff --git a/chrome/common/extensions/docs/server2/handlebar_dict_generator.py b/chrome/common/extensions/docs/server2/handlebar_dict_generator.py
index b6f1ffd..1d93f6a 100644
--- a/chrome/common/extensions/docs/server2/handlebar_dict_generator.py
+++ b/chrome/common/extensions/docs/server2/handlebar_dict_generator.py
@@ -34,6 +34,12 @@ def _GetLinkToRefType(namespace_name, ref_type):
     "text": text
   })
 
+def _FormatValue(value):
+  """Inserts commas every three digits for integer values. It is magic.
+  """
+  s = str(value)
+  return ','.join([s[max(0, i - 3):i] for i in range(len(s), 0, -3)][::-1])
+
 class HandlebarDictGenerator(object):
   """Uses a Model from the JSON Schema Compiler and generates a dict that
   a Handlebar template can use for a data source.
@@ -51,7 +57,8 @@ class HandlebarDictGenerator(object):
       return {
         'name': self._namespace.name,
         'types': self._GenerateTypes(self._namespace.types),
-        'functions': self._GenerateFunctions(self._namespace.functions)
+        'functions': self._GenerateFunctions(self._namespace.functions),
+        'properties': self._GenerateProperties(self._namespace.properties)
       }
     except Exception as e:
       logging.info(e)
@@ -98,6 +105,7 @@ class HandlebarDictGenerator(object):
       return {}
     callback_dict = {
       'name': 'callback',
+      'description': callback.description,
       'simple_type': {'type': 'function'},
       'optional': callback.optional,
       'parameters': []
@@ -119,9 +127,16 @@ class HandlebarDictGenerator(object):
       'name': property_.name,
       'optional': property_.optional,
       'description': property_.description,
-      'properties': self._GenerateProperties(property_.properties)
+      'properties': self._GenerateProperties(property_.properties),
+      'functions': self._GenerateFunctions(property_.functions)
     }
-    self._RenderTypeInformation(property_, property_dict)
+    if property_.has_value:
+      if isinstance(property_.value, int):
+        property_dict['value'] = _FormatValue(property_.value)
+      else:
+        property_dict['value'] = property_.value
+    else:
+      self._RenderTypeInformation(property_, property_dict)
     return property_dict
 
   def _RenderTypeInformation(self, property_, dst_dict):
diff --git a/chrome/common/extensions/docs/server2/handlebar_dict_generator_test.py b/chrome/common/extensions/docs/server2/handlebar_dict_generator_test.py
index e3cdbbc..db7fba4 100755
--- a/chrome/common/extensions/docs/server2/handlebar_dict_generator_test.py
+++ b/chrome/common/extensions/docs/server2/handlebar_dict_generator_test.py
@@ -9,6 +9,7 @@ import unittest
 
 from handlebar_dict_generator import HandlebarDictGenerator
 from handlebar_dict_generator import _GetLinkToRefType
+from handlebar_dict_generator import _FormatValue
 import third_party.json_schema_compiler.json_comment_eater as comment_eater
 import third_party.json_schema_compiler.model as model
 
@@ -40,5 +41,10 @@ class DictGeneratorTest(unittest.TestCase):
     self.assertEquals(link['href'], 'lies.html#type-chrome.bookmarks.Tab')
     self.assertEquals(link['text'], 'chrome.bookmarks.Tab')
 
+  def testFormatValue(self):
+    self.assertEquals('1,234,567', _FormatValue(1234567))
+    self.assertEquals('67', _FormatValue(67))
+    self.assertEquals('234,567', _FormatValue(234567))
+
 if __name__ == '__main__':
   unittest.main()
diff --git a/chrome/common/extensions/docs/server2/static/css/api.css b/chrome/common/extensions/docs/server2/static/css/api.css
index e831145..a674299 100644
--- a/chrome/common/extensions/docs/server2/static/css/api.css
+++ b/chrome/common/extensions/docs/server2/static/css/api.css
@@ -13,6 +13,13 @@
   margin-top: 1em;
 }
 
+/* This style is used because types with functions prefix the function with the
+ * type name, using a lowercase first letter.
+ */
+.api_reference div.summary:first-letter {
+  text-transform: lowercase;
+}
+
 .api_reference div.description {
   margin-left: 2em;
 }
diff --git a/chrome/common/extensions/docs/server2/static/css/site.css b/chrome/common/extensions/docs/server2/static/css/site.css
index 4efc23d..ba23e34 100644
--- a/chrome/common/extensions/docs/server2/static/css/site.css
+++ b/chrome/common/extensions/docs/server2/static/css/site.css
@@ -27,6 +27,14 @@ p.note {
   border-color: #36C;
 }
 
+p.caution {
+  border-color: #FC3;
+}
+
+p.warning {
+  border-color: #A03;
+}
+
 a, a:link {
   text-decoration: none;
   color: black;
diff --git a/chrome/common/extensions/docs/server2/templates/private/api_property.html b/chrome/common/extensions/docs/server2/templates/private/api_property.html
new file mode 100644
index 0000000..ddde3ab
--- /dev/null
+++ b/chrome/common/extensions/docs/server2/templates/private/api_property.html
@@ -0,0 +1,13 @@
+<div>
+  <a name="property-{{name}}"></a>
+  <h4>{{name}}</h4>
+  <div class="summary">
+    <span>chrome.{{api.name}}.{{name}}</span>
+  </div>
+  <div>
+    <dt><span class="property">{{name}}</span> {{+partials.type_name}}</dt>
+    <dd>{{{description}}}</dd>
+    <dd><dl>{{#properties}}{{+partials.property}}{{/}}</dl></dd>
+    <dd><dl>{{#functions}}{{+partials.function}}{{/}}</dl></dd>
+  </div>
+</div>
diff --git a/chrome/common/extensions/docs/server2/templates/private/api_reference.html b/chrome/common/extensions/docs/server2/templates/private/api_reference.html
index c542ee4..cfc8b0a 100644
--- a/chrome/common/extensions/docs/server2/templates/private/api_reference.html
+++ b/chrome/common/extensions/docs/server2/templates/private/api_reference.html
@@ -1,6 +1,12 @@
 <a name="apiReference"></a>
 <h2>API Reference: chrome.{{api.name}}</h2>
 <div class="api_reference">
+  {{?api.properties}}
+    <h3 id="properties">Properties</h3>
+    {{#api.properties}}
+      {{+partials.api_property api:api}}
+    {{/}}
+  {{/api.properties}}
   {{?api.functions}}
     <h3 id="methods">Methods</h3>
     {{#api.functions}}
@@ -16,7 +22,7 @@
   {{?api.types}}
     <h3 id="types">Types</h3>
     {{#api.types}}
-      {{+partials.type api:api}}
+      {{+partials.type api:api type:@}}
     {{/}}
   {{/api.types}}
 </div>
diff --git a/chrome/common/extensions/docs/server2/templates/private/function.html b/chrome/common/extensions/docs/server2/templates/private/function.html
index b62eec7..b2e5b1e 100644
--- a/chrome/common/extensions/docs/server2/templates/private/function.html
+++ b/chrome/common/extensions/docs/server2/templates/private/function.html
@@ -1,8 +1,8 @@
 <div>
-  <a name="method-{{name}}"></a>
+  <a name="method-{{?prefix}}{{prefix}}-{{/}}{{name}}"></a>
   <h4>{{name}}</h4>
   <div class="summary">
-    <span>chrome.{{api.name}}.{{name}}</span>({{#parameters}}{{+partials.parameter_item}}{{^last_item}}, {{/}}{{/}})
+    <span>{{?prefix}}{{prefix}}{{/}}{{^prefix}}chrome.{{api.name}}{{/}}.{{name}}</span>({{#parameters}}{{+partials.parameter_item}}{{^last_item}}, {{/}}{{/}})
   </div>
   <div class="description">
     <p>{{{description}}}</p>
diff --git a/chrome/common/extensions/docs/server2/templates/private/table_of_contents.html b/chrome/common/extensions/docs/server2/templates/private/table_of_contents.html
index 6e078b3..031272e 100644
--- a/chrome/common/extensions/docs/server2/templates/private/table_of_contents.html
+++ b/chrome/common/extensions/docs/server2/templates/private/table_of_contents.html
@@ -4,36 +4,12 @@
     <li>
       <a href="#apiReference">API reference: chrome.{{api.name}}</a>
       <ol>
-        {{?api.functions}}
-        <li>
-          <a href="#methods">Methods</a>
-          <ol>
-            {{#api.functions}}
-            <li><a href="#method-{{name}}">{{name}}</a></li>
-            {{/}}
-          </ol>
-        </li>
-        {{/api.functions}}
-        {{?api.events}}
-        <li>
-          <a href="#events">Events</a>
-          <ol>
-            {{#api.events}}
-            <li><a href="#event-{{name}}">{{name}}</a></li>
-            {{/}}
-          </ol>
-        </li>
-        {{/api.events}}
-        {{?api.types}}
-        <li>
-          <a href="#types">Types</a>
-          <ol>
-            {{#api.types}}
-            <li><a href="#type-{{name}}">{{name}}</a></li>
-            {{/}}
-          </ol>
-        </li>
-        {{/api.types}}
+        {{#api}}
+          {{?api.properties}}<li>{{+partials.toc_properties}}</li>{{/}}
+          {{?api.functions}}<li>{{+partials.toc_functions}}</li>{{/}}
+          {{?api.events}}<li>{{+partials.toc_events}}</li>{{/}}
+          {{?api.types}}<li>{{+partials.toc_types}}</li>{{/}}
+        {{/api}}
       </ol>
     </li>
   </ol>
diff --git a/chrome/common/extensions/docs/server2/templates/private/toc_events.html b/chrome/common/extensions/docs/server2/templates/private/toc_events.html
new file mode 100644
index 0000000..d1b94ab
--- /dev/null
+++ b/chrome/common/extensions/docs/server2/templates/private/toc_events.html
@@ -0,0 +1,6 @@
+<a href="#{{?prefix}}{{prefix}}-{{/}}events">Events</a>
+<ol>
+  {{#@}}
+  <li><a href="#event-{{?prefix}}{{prefix}}-{{/}}{{name}}">{{name}}</a></li>
+  {{/}}
+</ol>
diff --git a/chrome/common/extensions/docs/server2/templates/private/toc_functions.html b/chrome/common/extensions/docs/server2/templates/private/toc_functions.html
new file mode 100644
index 0000000..a94739b
--- /dev/null
+++ b/chrome/common/extensions/docs/server2/templates/private/toc_functions.html
@@ -0,0 +1,6 @@
+<a href="#{{?prefix}}{{prefix}}-{{/}}methods">Methods</a>
+<ol>
+  {{#@}}
+  <li><a href="#method-{{?prefix}}{{prefix}}-{{/}}{{name}}">{{name}}</a></li>
+  {{/}}
+</ol>
diff --git a/chrome/common/extensions/docs/server2/templates/private/toc_properties.html b/chrome/common/extensions/docs/server2/templates/private/toc_properties.html
new file mode 100644
index 0000000..eec6754
--- /dev/null
+++ b/chrome/common/extensions/docs/server2/templates/private/toc_properties.html
@@ -0,0 +1,8 @@
+<a href="#{{?prefix}}{{prefix}}-{{/}}properties">Properties</a>
+<ol>
+  {{#@}}
+  <li><a href="#property-{{?prefix}}{{prefix}}-{{/}}{{name}}">{{name}}</a></li>
+  {{?functions}}<ol><li>{{+partials.toc_functions prefix:name}}</li></ol>{{/}}
+  {{?events}}<ol><li>{{+partials.toc_events prefix:name}}</li></ol>{{/}}
+  {{/}}
+</ol>
diff --git a/chrome/common/extensions/docs/server2/templates/private/toc_types.html b/chrome/common/extensions/docs/server2/templates/private/toc_types.html
new file mode 100644
index 0000000..5b7f89b
--- /dev/null
+++ b/chrome/common/extensions/docs/server2/templates/private/toc_types.html
@@ -0,0 +1,10 @@
+<a href="#{{?prefix}}{{prefix}}-{{/}}types">Types</a>
+<ol>
+  {{#@}}
+  <li>
+    <a href="#type-{{?prefix}}{{prefix}}-{{/}}{{name}}">{{name}}</a>
+    {{?functions}}<ol><li>{{+partials.toc_functions prefix:name}}</li></ol>{{/}}
+    {{?events}}<ol><li>{{+partials.toc_events prefix:name}}</li></ol>{{/}}
+  </li>
+  {{/}}
+</ol>
diff --git a/chrome/common/extensions/docs/server2/templates/private/type.html b/chrome/common/extensions/docs/server2/templates/private/type.html
index d27ada7..31689bc 100644
--- a/chrome/common/extensions/docs/server2/templates/private/type.html
+++ b/chrome/common/extensions/docs/server2/templates/private/type.html
@@ -5,6 +5,10 @@
     <dt>{{+partials.type_name}}</dt>
     <dd>{{{description}}}</dd>
     <dd><dl>{{#properties}}{{+partials.property}}{{/}}</dl></dd>
-    <dd><dl>{{#functions}}{{+partials.function api:api}}{{/}}</dl></dd>
+    {{?functions}}
+    <a name={{type.name}}-methods></a>
+    <dd><h3>Methods of {{type.name}}</h3>
+      <dd><dl>{{#functions}}{{+partials.function api:api prefix:type.name}}{{/}}</dl></dd>
+    {{/functions}}
   </div>
 </div>
diff --git a/chrome/common/extensions/docs/server2/templates/private/variable_type.html b/chrome/common/extensions/docs/server2/templates/private/variable_type.html
index 7cb470d..bc23eba 100644
--- a/chrome/common/extensions/docs/server2/templates/private/variable_type.html
+++ b/chrome/common/extensions/docs/server2/templates/private/variable_type.html
@@ -2,3 +2,4 @@
 {{#choices}}{{+partials.variable_type}}{{^last_choice}} or {{/}}{{/}}
 {{?array}}array of {{+partials.variable_type}}{{/}}
 {{?simple_type}}{{type}}{{/}}
+{{?value}}<code>{{value}}</code>{{/}}
diff --git a/chrome/common/extensions/docs/server2/test_data/test_json/expected_test_file.json b/chrome/common/extensions/docs/server2/test_data/test_json/expected_test_file.json
index 1e7ab07..fafb910 100644
--- a/chrome/common/extensions/docs/server2/test_data/test_json/expected_test_file.json
+++ b/chrome/common/extensions/docs/server2/test_data/test_json/expected_test_file.json
@@ -2,12 +2,18 @@
   "functions": [
     {
       "callback": {
+        "simple_type": {
+          "type": "function"
+        },
+        "name": "callback",
         "parameters": [
           {
+            "functions": [],
             "name": "results",
             "optional": false,
             "last_parameter": true,
             "array": {
+              "functions": [],
               "name": "resultsElement",
               "optional": false,
               "link": {
@@ -23,20 +29,19 @@
             "description": null
           }
         ],
+        "last_item": true,
         "optional": false,
-        "name": "callback",
-        "simple_type": {
-          "type": "function"
-        },
-        "last_item": true
+        "description": null
       },
       "name": "get",
       "parameters": [
         {
+          "functions": [],
           "name": "a",
           "optional": false,
           "choices": [
             {
+              "functions": [],
               "name": "a",
               "simple_type": {
                 "type": "string"
@@ -48,9 +53,11 @@
             },
             {
               "last_choice": true,
+              "functions": [],
               "name": "a",
               "optional": true,
               "array": {
+                "functions": [],
                 "name": "aElement",
                 "simple_type": {
                   "type": "string"
@@ -70,12 +77,18 @@
           "description": "a param"
         },
         {
+          "simple_type": {
+            "type": "function"
+          },
+          "name": "callback",
           "parameters": [
             {
+              "functions": [],
               "name": "results",
               "optional": false,
               "last_parameter": true,
               "array": {
+                "functions": [],
                 "name": "resultsElement",
                 "optional": false,
                 "link": {
@@ -91,12 +104,9 @@
               "description": null
             }
           ],
+          "last_item": true,
           "optional": false,
-          "name": "callback",
-          "simple_type": {
-            "type": "function"
-          },
-          "last_item": true
+          "description": null
         }
       ],
       "description": "Gets stuff."
@@ -113,9 +123,11 @@
       "type": "object",
       "properties": [
         {
+          "functions": [],
           "name": "b",
           "optional": true,
           "array": {
+            "functions": [],
             "name": "bElement",
             "optional": false,
             "link": {
@@ -133,5 +145,6 @@
       ],
       "description": "A cool thing."
     }
-  ]
+  ],
+  "properties": []
 }