[Extension API Extern Generation] Add support for function types

Instead of just having Function or Function= for each callback, use the
function() Closure Compiler type documentation.  Additionally, add support for
@deprecated function documentation.

BUG=461039

Review URL: https://codereview.chromium.org/1036593004

Cr-Commit-Position: refs/heads/master@{#322285}

tools/json_schema_compiler/js_externs_generator.py

@@ -139,40 +139,46 @@ class _Generator(object):
     c = Code()
     c.Append('/**')
 
+    lines = []
     if function.description:
-      for line in function.description.split('\n'):
-        c.Comment(line, comment_prefix=' * ')
+      lines.extend(function.description.splitlines())
 
     for param in function.params:
       js_type = self._TypeToJsType(param.type_)
-
       if param.optional:
         js_type += '='
-
-      param_doc = '@param {%s} %s %s' % (js_type,
-                                         param.name,
-                                         param.description or '')
-      c.Comment(param_doc, comment_prefix=' * ')
+      lines.append('@param {%s} %s %s' % (js_type,
+                                          param.name,
+                                          param.description or ''))
 
     if function.callback:
-      # TODO(tbreisacher): Convert Function to function() for better
-      # typechecking.
-      js_type = 'Function'
-      if function.callback.optional:
-        js_type += '='
-      param_doc = '@param {%s} %s %s' % (js_type,
-                                         function.callback.name,
-                                         function.callback.description or '')
-      c.Comment(param_doc, comment_prefix=' * ')
+      lines.append('@param {%s} %s %s' % (
+          self._FunctionToJsFunction(function.callback),
+          function.callback.name,
+          function.callback.description or ''))
 
     if function.returns:
-      return_doc = '@return {%s} %s' % (self._TypeToJsType(function.returns),
-                                        function.returns.description)
-      c.Comment(return_doc, comment_prefix=' * ')
+      lines.append('@return {%s} %s' % (self._TypeToJsType(function.returns),
+                                        function.returns.description or ''))
+
+    if function.deprecated:
+      lines.append('@deprecated %s' % function.deprecated)
+
+    for line in lines:
+      c.Comment(line, comment_prefix=' * ');
 
     c.Append(' */')
     return c
 
+  def _FunctionToJsFunction(self, function):
+    """Converts a model.Function to a JS type (i.e., function([params])...)"""
+    params = ', '.join(
+        [self._TypeToJsType(param.type_) for param in function.params])
+    return_type = (
+        self._TypeToJsType(function.returns) if function.returns else 'void')
+    optional = '=' if function.optional else ''
+    return 'function(%s):%s%s' % (params, return_type, optional)
+
   def _TypeToJsType(self, js_type):
     """Converts a model.Type to a JS type (number, Array, etc.)"""
     if js_type.property_type in (PropertyType.INTEGER, PropertyType.DOUBLE):
@@ -191,6 +197,8 @@ class _Generator(object):
     elif js_type.property_type is PropertyType.CHOICES:
       return '(%s)' % '|'.join(
           [self._TypeToJsType(choice) for choice in js_type.choices])
+    elif js_type.property_type is PropertyType.FUNCTION:
+      return self._FunctionToJsFunction(js_type.function)
     elif js_type.property_type is PropertyType.ANY:
       return '*'
     elif js_type.property_type.is_fundamental:

tools/json_schema_compiler/js_externs_generator_test.py

@@ -46,10 +46,17 @@ namespace fakeApi {
 
   callback VoidCallback = void();
 
+  callback BazGreekCallback = void(Baz baz, Greek greek);
+
   interface Functions {
-    // Does something exciting!
+    // Does something exciting! And what's more, this is a multiline function
+    // comment! It goes onto multiple lines!
     // |baz| : The baz to use.
-    static void doSomething(Baz baz, optional VoidCallback callback);
+    static void doSomething(Baz baz, VoidCallback callback);
+
+    static void bazGreek(optional BazGreekCallback callback);
+
+    [deprecated="Use a new method."] static DOMString returnString();
   };
 };
 """
@@ -102,11 +109,23 @@ var Bar;
 var Baz;
 
 /**
- * Does something exciting!
+ * Does something exciting! And what's more, this is a multiline function
+ * comment! It goes onto multiple lines!
  * @param {Baz} baz The baz to use.
- * @param {Function=} callback
+ * @param {function():void} callback
  */
 chrome.fakeApi.doSomething = function(baz, callback) {};
+
+/**
+ * @param {function(Baz, !chrome.fakeApi.Greek):void=} callback
+ */
+chrome.fakeApi.bazGreek = function(callback) {};
+
+/**
+ * @return {string}
+ * @deprecated Use a new method.
+ */
+chrome.fakeApi.returnString = function() {};
 """ % datetime.now().year