Allow IDL schemas to have comments on callback functions

The JSON schema compiler was ignoring comments on callback functions. Now
callback functions and their parameters can have comments.

BUG=158459

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

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

4 files changed, 40 insertions, 7 deletions

diff --git a/chrome/common/extensions/docs/templates/private/callback.html b/chrome/common/extensions/docs/templates/private/callback.html
index c6a52bc..11c7a99 100644
--- a/chrome/common/extensions/docs/templates/private/callback.html
+++ b/chrome/common/extensions/docs/templates/private/callback.html
@@ -9,6 +9,9 @@
   {{/}}
 </p>
 <pre>function({{#parameters}}{{+partials.variable_type}} {{name}}{{^last}}, {{/}}{{/}}) <span class="subdued">{...}</span>;</pre>
+{{?description}}<p>
+  {{description}}
+</p>{{/}}
 <dl>
   {{#parameters}}{{+partials.parameter_full}}{{/}}
 </dl>
diff --git a/tools/json_schema_compiler/idl_schema.py b/tools/json_schema_compiler/idl_schema.py
index 1785b34..30dad11 100644
--- a/tools/json_schema_compiler/idl_schema.py
+++ b/tools/json_schema_compiler/idl_schema.py
@@ -57,7 +57,7 @@ def ProcessComment(comment):
     )
   '''
   # Find all the parameter comments of the form '|name|: comment'.
-  parameter_starts = list(re.finditer(r'\n *\|([^|]*)\| *: *', comment))
+  parameter_starts = list(re.finditer(r' *\|([^|]*)\| *: *', comment))
 
   # Get the parent comment (everything before the first parameter comment.
   first_parameter_location = (parameter_starts[0].start()
@@ -229,10 +229,16 @@ class Typeref(object):
       properties['type'] = 'function'
     else:
       if self.typeref in callbacks:
+        # Do not override name and description if they are already specified.
+        name = properties.get('name', None)
+        description = properties.get('description', None)
         properties.update(callbacks[self.typeref])
+        if description is not None:
+          properties['description'] = description
+        if name is not None:
+          properties['name'] = name
       else:
         properties['$ref'] = self.typeref
-
     return result
 
 
diff --git a/tools/json_schema_compiler/idl_schema_test.py b/tools/json_schema_compiler/idl_schema_test.py
index bca451b..a710323 100755
--- a/tools/json_schema_compiler/idl_schema_test.py
+++ b/tools/json_schema_compiler/idl_schema_test.py
@@ -30,20 +30,20 @@ class IdlSchemaTest(unittest.TestCase):
 
   def testSimpleCallbacks(self):
     schema = self.idl_basics
-    expected = [{'type':'function', 'name':'Callback1', 'parameters':[]}]
+    expected = [{'type':'function', 'name':'cb', 'parameters':[]}]
     self.assertEquals(expected, getParams(schema, 'function4'))
 
-    expected = [{'type':'function', 'name':'Callback2',
+    expected = [{'type':'function', 'name':'cb',
                  'parameters':[{'name':'x', 'type':'integer'}]}]
     self.assertEquals(expected, getParams(schema, 'function5'))
 
-    expected = [{'type':'function', 'name':'Callback3',
+    expected = [{'type':'function', 'name':'cb',
                  'parameters':[{'name':'arg', '$ref':'idl_basics.MyType1'}]}]
     self.assertEquals(expected, getParams(schema, 'function6'))
 
   def testCallbackWithArrayArgument(self):
     schema = self.idl_basics
-    expected = [{'type':'function', 'name':'Callback4',
+    expected = [{'type':'function', 'name':'cb',
                  'parameters':[{'name':'arg', 'type':'array',
                                 'items':{'$ref':'idl_basics.MyType2'}}]}]
     self.assertEquals(expected, getParams(schema, 'function12'))
@@ -70,7 +70,7 @@ class IdlSchemaTest(unittest.TestCase):
     self.assertEquals(expected, getType(schema, expected['id']))
 
     expected = [{'name':'type', '$ref':'idl_basics.EnumType'},
-                {'type':'function', 'name':'Callback5',
+                {'type':'function', 'name':'cb',
                   'parameters':[{'name':'type', '$ref':'idl_basics.EnumType'}]}]
     self.assertEquals(expected, getParams(schema, 'function13'))
 
@@ -90,6 +90,20 @@ class IdlSchemaTest(unittest.TestCase):
     self.assertTrue(idl_basics['internal'])
     self.assertFalse(idl_basics['nodoc'])
 
+  def testCallbackComment(self):
+    schema = self.idl_basics
+    self.assertEquals('A comment on a callback.',
+                      getParams(schema, 'function16')[0]['description'])
+    self.assertEquals(
+        'A parameter.',
+        getParams(schema, 'function16')[0]['parameters'][0]['description'])
+    self.assertEquals(
+        'Just a parameter comment, with no comment on the callback.',
+        getParams(schema, 'function17')[0]['parameters'][0]['description'])
+    self.assertEquals(
+        'Override callback comment.',
+        getParams(schema, 'function18')[0]['description'])
+
   def testFunctionComment(self):
     schema = self.idl_basics
     func = getFunction(schema, 'function3')
diff --git a/tools/json_schema_compiler/test/idl_basics.idl b/tools/json_schema_compiler/test/idl_basics.idl
index eb4ec62..f4e1b3ca 100644
--- a/tools/json_schema_compiler/test/idl_basics.idl
+++ b/tools/json_schema_compiler/test/idl_basics.idl
@@ -26,6 +26,11 @@
   callback Callback3 = void(MyType1 arg);
   callback Callback4 = void(MyType2[] arg);
   callback Callback5 = void(EnumType type);
+  // A comment on a callback.
+  // |x|: A parameter.
+  callback Callback6 = void(long x);
+  // |x|: Just a parameter comment, with no comment on the callback.
+  callback Callback7 = void(long x);
 
   interface Functions {
     static void function1();
@@ -60,6 +65,11 @@
     // "switch" is a reserved word and should cause a C++ compile error if we
     // emit code for this declaration.
     [nocompile] static void function15(long switch);
+
+    static void function16(Callback6 cb);
+    static void function17(Callback7 cb);
+    // |cb|: Override callback comment.
+    static void function18(Callback7 cb);
   };
 
   interface Events {