[Extension API Extern Generation] Add support for function types

tools/json_schema_compiler/js_externs_generator.py

 # Copyright 2015 The Chromium Authors. All rights reserved.
 # Use of this source code is governed by a BSD-style license that can be
 # found in the LICENSE file.
 """
 Generator that produces an externs file for the Closure Compiler.
 Note: This is a work in progress, and generated externs may require tweaking.
 
 See https://developers.google.com/closure/compiler/docs/api-tutorial3#externs
 """
 
@@ skipping 121 matching lines @@
     return c
 
   def _GenerateFunctionJsDoc(self, function):
     """Generates the documentation for a function as a Code.
 
     Returns an empty code object if the object has no documentation.
     """
     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):
       return 'number'
     elif js_type.property_type is PropertyType.OBJECT:
       return 'Object'
     elif js_type.property_type is PropertyType.ARRAY:
       return '!Array<%s>' % self._TypeToJsType(js_type.item_type)
     elif js_type.property_type is PropertyType.REF:
       ref_type = js_type.ref_type
       # Enums are defined as chrome.fooAPI.MyEnum, but types are defined simply
       # as MyType.
       if self._namespace.types[ref_type].property_type is PropertyType.ENUM:
         ref_type = '!chrome.%s.%s' % (self._namespace.name, ref_type)
       return ref_type
     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:
       return js_type.property_type.name
     else:
       return '?' # TODO(tbreisacher): Make this more specific.
 
   def _GenerateFunction(self, function):
     """Generates the code representing a function, including its documentation.
        For example:
@@ skipping 38 matching lines @@
  * @const
  */""")
       .Append('chrome.%s = {};' % self._namespace.name))
     return c
 
   def _GenerateFunctionParams(self, function):
     params = function.params[:]
     if function.callback:
       params.append(function.callback)
     return ', '.join(param.name for param in params)