[Extension API Extern Generation] Auto-generate enums

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 20 matching lines @@
   def Generate(self):
     """Generates a Code object with the schema for the entire namespace.
     """
     c = Code()
     (c.Append(LICENSE)
         .Append()
         .Append('/** @fileoverview Externs generated from namespace: %s */' %
                 self._namespace.name)
         .Append())
 
+    c.Cblock(self._GenerateNamespaceObject())
+
     for js_type in self._namespace.types.values():
       c.Cblock(self._GenerateType(js_type))
 
-    c.Cblock(self._GenerateNamespaceObject())
-
     for function in self._namespace.functions.values():
       c.Cblock(self._GenerateFunction(function))
 
     for event in self._namespace.events.values():
       c.Cblock(self._GenerateEvent(event))
 
     return c
 
   def _GenerateType(self, js_type):
     """Given a Type object, returns the Code for this type's definition.
-
     """
     c = Code()
-
-    # Since enums are just treated as strings for now, don't generate their
-    # type.
     if js_type.property_type is PropertyType.ENUM:
-      return c
-
-    c.Concat(self._GenerateTypeJsDoc(js_type))
-
-    var = 'var ' + js_type.simple_name
-    if self._IsTypeConstructor(js_type): var += ' = function()'
-    var += ';'
-    c.Append(var)
+      c.Concat(self._GenerateEnumJsDoc(js_type))
+    else:
+      c.Concat(self._GenerateTypeJsDoc(js_type))
 
     return c
 
+  def _GenerateEnumJsDoc(self, js_type):
+    """ Given an Enum Type object, returns the Code for the enum's definition.
+    """
+    c = Code()
+    c.Append('/**').Append(' * @enum {string}').Append(' */')
+    c.Append('chrome.%s.%s = {' % (self._namespace.name, js_type.name))
+    value_lines = []
+    for value in [v.name for v in js_type.enum_values]:
+      value_lines.append("  %s: '%s'," % (value, value))

[Tyler Breisacher (Chromium), 2015/03/24 20:07:52]

It seems a bit strange to have a list comp and then iterate over it. Would this
work?

for v in js_type.enum_values:
  value_lines.append("  %s: '%s'," % (v.name, v.name))

or perhaps just do it all in one list comp:

value_lines = ["  %s: '%s'," % (v.name, v.name) for v in js_type.enum_values]

[Devlin, 2015/03/24 20:31:55]

Done.

+    # Remove last trailing comma.
+    # TODO(devlin): This will be unneeded, if when

[Tyler Breisacher (Chromium), 2015/03/24 20:07:52]

Actually I think you can drop line 77 now, because this is code, not JsDoc, and
it should be parsed according to the ES5 grammar.

[Devlin, 2015/03/24 20:31:55]

Done.

+    # https://github.com/google/closure-compiler/issues/796 is fixed.
+    value_lines[-1] = value_lines[-1][:-1]
+    c.Append('\n'.join(value_lines))
+    c.Append('};')
+    return c
+
   def _IsTypeConstructor(self, js_type):
     """Returns true if the given type should be a @constructor. If this returns
        false, the type is a typedef.
     """
     return any(prop.type_.property_type is PropertyType.FUNCTION
                for prop in js_type.properties.values())
 
   def _GenerateTypeJsDoc(self, js_type):
     """Generates the documentation for a type as a Code.
 
     Returns an empty code object if the object has no documentation.
     """
     c = Code()
     c.Append('/**')
 
     if js_type.description:
       for line in js_type.description.splitlines():
         c.Comment(line, comment_prefix = ' * ')
 
-    if self._IsTypeConstructor(js_type):
+    is_constructor = self._IsTypeConstructor(js_type)
+    if is_constructor:
       c.Comment('@constructor', comment_prefix = ' * ')
     else:
       c.Concat(self._GenerateTypedef(js_type.properties))
 
     c.Append(' */')
+
+    var = 'var ' + js_type.simple_name
+    if is_constructor: var += ' = function()'

[Tyler Breisacher (Chromium), 2015/03/24 20:07:52]

I think you need the body too:

if is_constructor: var += ' = function() {}'

[Devlin, 2015/03/24 20:31:55]

I would have thought so, too, but figured maybe there some was weirdness with
constructors (since it was this way before).  Anyway, added the body.

+    var += ';'
+    c.Append(var)
+
     return c
 
   def _GenerateTypedef(self, properties):
     """Given an OrderedDict of properties, returns a Code containing a @typedef.
     """
     if not properties: return Code()
 
     lines = []
     lines.append('@typedef {{')
     for field, prop in properties.items():
@@ skipping 57 matching lines @@
 
   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'
     elif js_type.property_type is PropertyType.REF:
-      return js_type.ref_type
+      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_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 36 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)