Docserver: Display enum value descriptions in API docs.

This modifies the json schema to allow both primitive types and
dictionaries with properties "name" and optional "description" for enum
values.

BUG=310454

Committed: https://src.chromium.org/viewvc/chrome?view=rev&revision=231982

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

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

6 files changed, 36 insertions, 9 deletions

diff --git a/tools/json_schema_compiler/cc_generator.py b/tools/json_schema_compiler/cc_generator.py
index 9935e1c..371c60d 100644
--- a/tools/json_schema_compiler/cc_generator.py
+++ b/tools/json_schema_compiler/cc_generator.py
@@ -784,7 +784,9 @@ class _Generator(object):
                                  self._type_helper.GetEnumNoneValue(type_)))
       .Concat(self._GenerateError(
         '\"\'%%(key)s\': expected \\"' +
-        '\\" or \\"'.join(self._type_helper.FollowRef(type_).enum_values) +
+        '\\" or \\"'.join(
+            enum_value.name
+            for enum_value in self._type_helper.FollowRef(type_).enum_values) +
         '\\", got \\"" + %s + "\\""' % enum_as_string))
       .Append('return %s;' % failure_value)
       .Eblock('}')
@@ -820,7 +822,7 @@ class _Generator(object):
     c.Sblock('switch (enum_param) {')
     for enum_value in self._type_helper.FollowRef(type_).enum_values:
       (c.Append('case %s: ' % self._type_helper.GetEnumValue(type_, enum_value))
-        .Append('  return "%s";' % enum_value))
+        .Append('  return "%s";' % enum_value.name))
     (c.Append('case %s:' % self._type_helper.GetEnumNoneValue(type_))
       .Append('  return "";')
       .Eblock('}')
@@ -848,7 +850,7 @@ class _Generator(object):
       # This is broken up into all ifs with no else ifs because we get
       # "fatal error C1061: compiler limit : blocks nested too deeply"
       # on Windows.
-      (c.Append('if (enum_string == "%s")' % enum_value)
+      (c.Append('if (enum_string == "%s")' % enum_value.name)
         .Append('  return %s;' %
             self._type_helper.GetEnumValue(type_, enum_value)))
     (c.Append('return %s;' % self._type_helper.GetEnumNoneValue(type_))
diff --git a/tools/json_schema_compiler/cpp_type_generator.py b/tools/json_schema_compiler/cpp_type_generator.py
index 4c0306d..d485b46 100644
--- a/tools/json_schema_compiler/cpp_type_generator.py
+++ b/tools/json_schema_compiler/cpp_type_generator.py
@@ -65,7 +65,7 @@ class CppTypeGenerator(object):
     e.g VAR_STRING
     """
     value = '%s_%s' % (self.FollowRef(type_).unix_name.upper(),
-                       cpp_util.Classname(enum_value.upper()))
+                       cpp_util.Classname(enum_value.name.upper()))
     # To avoid collisions with built-in OS_* preprocessor definitions, we add a
     # trailing slash to enum names that start with OS_.
     if value.startswith("OS_"):
diff --git a/tools/json_schema_compiler/idl_schema.py b/tools/json_schema_compiler/idl_schema.py
index e33f8f0..238fb05 100644
--- a/tools/json_schema_compiler/idl_schema.py
+++ b/tools/json_schema_compiler/idl_schema.py
@@ -292,7 +292,13 @@ class Enum(object):
     enum = []
     for node in self.node.children:
       if node.cls == 'EnumItem':
-        enum.append(node.GetName())
+        enum_value = {'name': node.GetName()}
+        for child in node.children:
+          if child.cls == 'Comment':
+            enum_value['description'] = ProcessComment(child.GetName())[0]
+          else:
+            raise ValueError('Did not process %s %s' % (child.cls, child))
+        enum.append(enum_value)
       elif node.cls == 'Comment':
         self.description = ProcessComment(node.GetName())[0]
       else:
diff --git a/tools/json_schema_compiler/idl_schema_test.py b/tools/json_schema_compiler/idl_schema_test.py
index e0c987e..0840058 100755
--- a/tools/json_schema_compiler/idl_schema_test.py
+++ b/tools/json_schema_compiler/idl_schema_test.py
@@ -77,7 +77,9 @@ class IdlSchemaTest(unittest.TestCase):
 
   def testEnum(self):
     schema = self.idl_basics
-    expected = {'enum': ['name1', 'name2'], 'description': 'Enum description',
+    expected = {'enum': [{'name': 'name1', 'description': 'comment1'},
+                         {'name': 'name2'}],
+                'description': 'Enum description',
                 'type': 'string', 'id': 'EnumType'}
     self.assertEquals(expected, getType(schema, expected['id']))
 
@@ -162,10 +164,12 @@ class IdlSchemaTest(unittest.TestCase):
     schema = idl_schema.Load('test/idl_reserved_words.idl')[0]
 
     foo_type = getType(schema, 'Foo')
-    self.assertEquals(['float', 'DOMString'], foo_type['enum'])
+    self.assertEquals([{'name': 'float'}, {'name': 'DOMString'}],
+                      foo_type['enum'])
 
     enum_type = getType(schema, 'enum')
-    self.assertEquals(['callback', 'namespace'], enum_type['enum'])
+    self.assertEquals([{'name': 'callback'}, {'name': 'namespace'}],
+                      enum_type['enum'])
 
     dictionary = getType(schema, 'dictionary')
     self.assertEquals('integer', dictionary['properties']['long']['type'])
diff --git a/tools/json_schema_compiler/model.py b/tools/json_schema_compiler/model.py
index 7507ae7..3de975c 100644
--- a/tools/json_schema_compiler/model.py
+++ b/tools/json_schema_compiler/model.py
@@ -141,7 +141,7 @@ class Type(object):
       self.ref_type = json['$ref']
     elif 'enum' in json and json_type == 'string':
       self.property_type = PropertyType.ENUM
-      self.enum_values = [value for value in json['enum']]
+      self.enum_values = [EnumValue(value) for value in json['enum']]
     elif json_type == 'any':
       self.property_type = PropertyType.ANY
     elif json_type == 'binary':
@@ -343,6 +343,20 @@ class Property(object):
 
   unix_name = property(GetUnixName, SetUnixName)
 
+class EnumValue(object):
+  """A single value from an enum.
+  Properties:
+  - |name| name of the property as in the json.
+  - |description| a description of the property (if provided)
+  """
+  def __init__(self, json):
+    if isinstance(json, dict):
+      self.name = json['name']
+      self.description = json.get('description')
+    else:
+      self.name = json
+      self.description = None
+
 class _Enum(object):
   """Superclass for enum types with a "name" field, setting up repr/eq/ne.
   Enums need to do this so that equality/non-equality work over pickling.
diff --git a/tools/json_schema_compiler/test/idl_basics.idl b/tools/json_schema_compiler/test/idl_basics.idl
index 08d369c..05b09c5 100644
--- a/tools/json_schema_compiler/test/idl_basics.idl
+++ b/tools/json_schema_compiler/test/idl_basics.idl
@@ -7,6 +7,7 @@
 [internal] namespace idl_basics {
   // Enum description
   enum EnumType {
+    // comment1
     name1,
     name2
   };