Extensions Docs Server: Server code for showing properties of properties

chrome/common/extensions/docs/server2/handlebar_dict_generator.py

 # Copyright (c) 2012 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.
 
 import copy
 import os
 
 from docs_server_utils import GetLinkToRefType
 import third_party.json_schema_compiler.model as model
 
 def _RemoveNoDocs(item):
   if type(item) == dict:
     if item.get('nodoc', False):
       return True
     for key, value in item.items():
       if _RemoveNoDocs(value):
         del item[key]
   elif type(item) == list:
     for i in item:
       if _RemoveNoDocs(i):
         item.remove(i)
   return False
 
+def _CreateId(name, parent, prefix):

[not at google - send to devlin, 2012/10/03 01:07:26]

It would be a bit nicer to have parent be an optional parameter for
self-documentation, even though sometimes when you call this you don't know
whether there's a parent or not.

Actually... if you pass in the model object itself, it can figure out the parent
from that? Though see comment below about the "simple_name" stuff. That goes for
everywhere in this file where you've added a "parent" parameter to functions.

[cduvall, 2012/10/05 01:13:26]

Done.

+  if parent:

[not at google - send to devlin, 2012/10/03 01:07:26]

"is not None" or whatever?

[cduvall, 2012/10/05 01:13:26]

Done.

+    return '-'.join([prefix, parent, name])
+  return '-'.join([prefix, name])
+
 def _FormatValue(value):
   """Inserts commas every three digits for integer values. It is magic.
   """
   s = str(value)
   return ','.join([s[max(0, i - 3):i] for i in range(len(s), 0, -3)][::-1])
 
 class HandlebarDictGenerator(object):
   """Uses a Model from the JSON Schema Compiler and generates a dict that
   a Handlebar template can use for a data source.
   """
@@ skipping 28 matching lines @@
       ref_dict = GetLinkToRefType(self._namespace.name, ref)
       formatted_description.append('<a href="%(href)s">%(text)s</a>%(rest)s' %
           { 'href': ref_dict['href'], 'text': ref_dict['text'], 'rest': rest })
     return ''.join(formatted_description)
 
   def Generate(self):
     if self._namespace is None:
       return {}
     return {
       'name': self._namespace.name,
-      'types': map(self._GenerateType, self._namespace.types.values()),
-      'functions': self._GenerateFunctions(self._namespace.functions),
-      'events': map(self._GenerateEvent, self._namespace.events.values()),
-      'properties': self._GenerateProperties(self._namespace.properties)
+      'types':  [self._GenerateType(t) for t in self._namespace.types.values()
+                 if t.type_ != model.PropertyType.ADDITIONAL_PROPERTIES],
+      'functions': self._GenerateFunctions(self._namespace.functions, None),
+      'events': self._GenerateEvents(self._namespace.events, None),
+      'properties': self._GenerateProperties(self._namespace.properties, None)
     }
 
   def _GenerateType(self, type_):
+    name = self._StripPrefix(type_.name)
     type_dict = {
-      'name': self._StripPrefix(type_.name),
+      'name': name,
       'description': self._FormatDescription(type_.description),
-      'properties': self._GenerateProperties(type_.properties),
-      'functions': self._GenerateFunctions(type_.functions),
-      'events': map(self._GenerateEvent, type_.events.values())
+      'properties': self._GenerateProperties(type_.properties, name),
+      'functions': self._GenerateFunctions(type_.functions, name),
+      'events': self._GenerateEvents(type_.events, name),
+      'id': _CreateId(name, None, 'type')
     }
     self._RenderTypeInformation(type_, type_dict)
     return type_dict
 
-  def _GenerateFunctions(self, functions):
-    return map(self._GenerateFunction, functions.values())
+  def _GenerateFunctions(self, functions, parent):

[not at google - send to devlin, 2012/10/03 01:07:26]

Again, make parent explicitly optional, though you might not actually need it.

[cduvall, 2012/10/05 01:13:26]

Done.

+    return [self._GenerateFunction(f, parent) for f in functions.values()]
 
-  def _GenerateFunction(self, function):
+  def _GenerateFunction(self, function, parent):
     function_dict = {
       'name': function.name,
       'description': self._FormatDescription(function.description),
       'callback': self._GenerateCallback(function.callback),
       'parameters': [],
-      'returns': None
+      'returns': None,
+      'parent': parent,
+      'id': _CreateId(function.name, parent, 'method')
     }
     if function.returns:
       function_dict['returns'] = self._GenerateProperty(function.returns)
     for param in function.params:
       function_dict['parameters'].append(self._GenerateProperty(param))
     if function_dict['callback']:
       function_dict['parameters'].append(function_dict['callback'])
     if len(function_dict['parameters']) > 0:
       function_dict['parameters'][-1]['last'] = True
     return function_dict
 
-  def _GenerateEvent(self, event):
+  def _GenerateEvents(self, events, parent):
+    return [self._GenerateEvent(e, parent) for e in events.values()]
+
+  def _GenerateEvent(self, event, parent):
+    name = self._StripPrefix(event.name)
     event_dict = {
-      'name': self._StripPrefix(event.name),
+      'name': name,
       'description': self._FormatDescription(event.description),
       'parameters': map(self._GenerateProperty, event.params),
       'callback': self._GenerateCallback(event.callback),
       'conditions': [GetLinkToRefType(self._namespace.name, c)
                      for c in event.conditions],
       'actions': [GetLinkToRefType(self._namespace.name, a)
                      for a in event.actions],
       'filters': map(self._GenerateProperty, event.filters),
-      'supportsRules': event.supports_rules
+      'supportsRules': event.supports_rules,
+      'parent': parent,
+      'id': _CreateId(name, parent, 'event')
     }
     if event_dict['callback']:
       event_dict['parameters'].append(event_dict['callback'])
     if len(event_dict['parameters']) > 0:
       event_dict['parameters'][-1]['last'] = True
     return event_dict
 
   def _GenerateCallback(self, callback):
     if not callback:
       return None
     callback_dict = {
       'name': callback.name,
       'description': self._FormatDescription(callback.description),
       'simple_type': {'simple_type': 'function'},
       'optional': callback.optional,
       'parameters': []
     }
     for param in callback.params:
       callback_dict['parameters'].append(self._GenerateProperty(param))
     if (len(callback_dict['parameters']) > 0):
       callback_dict['parameters'][-1]['last'] = True
     return callback_dict
 
-  def _GenerateProperties(self, properties):
-    return map(self._GenerateProperty, properties.values())
+  def _GenerateProperties(self, properties, parent):
+    return [self._GenerateProperty(v, parent) for v in properties.values()
+            if v.type_ != model.PropertyType.ADDITIONAL_PROPERTIES]
 
-  def _GenerateProperty(self, property_):
+  def _GenerateProperty(self, property_, parent=None):
+    name = self._StripPrefix(property_.name)
     property_dict = {
-      'name': self._StripPrefix(property_.name),
+      'name': name,
       'optional': property_.optional,
       'description': self._FormatDescription(property_.description),
-      'properties': self._GenerateProperties(property_.properties),
-      'functions': self._GenerateFunctions(property_.functions)
+      'properties': self._GenerateProperties(property_.properties, name),
+      'functions': self._GenerateFunctions(property_.functions, name),

[not at google - send to devlin, 2012/10/03 01:07:26]

It's confusing to me that "parent" is actually "name of parent". Could you just
pass the parent in directly, and let the template code that uses it fish out the
name? It would mean pushing the _StripName logic into the JSON schema compiler
model, but that should be easy enough, right? It's possible to figure out the
namespace of an object and strip out the prefix. You could call it "simple_name"
or something (matches the Java reflection API).

[cduvall, 2012/10/05 01:13:26]

Done. I named this 'parent_name' instead, and added the 'simple_name' property
to the JSON schema compiler. This removed the need to pass parents around at all
to the functions.

+      'parent': parent,
+      'id': _CreateId(name, parent, 'property')
     }
     if property_.has_value:
       if isinstance(property_.value, int):
         property_dict['value'] = _FormatValue(property_.value)
       else:
         property_dict['value'] = property_.value
     else:
       self._RenderTypeInformation(property_, property_dict)
     return property_dict
 
   def _RenderTypeInformation(self, property_, dst_dict):
     if property_.type_ == model.PropertyType.CHOICES:
       dst_dict['choices'] = map(self._GenerateProperty,
                                 property_.choices.values())
       # We keep track of which is last for knowing when to add "or" between
       # choices in templates.
       if len(dst_dict['choices']) > 0:
         dst_dict['choices'][-1]['last'] = True
-    elif property_.type_ == model.PropertyType.ADDITIONAL_PROPERTIES:
-      dst_dict['additional_properties'] = True
     elif property_.type_ == model.PropertyType.REF:
       dst_dict['link'] = GetLinkToRefType(self._namespace.name,
                                           property_.ref_type)
     elif property_.type_ == model.PropertyType.ARRAY:
-      dst_dict['array'] = self._GenerateProperty(property_.item_type)
+      dst_dict['array'] = self._GenerateProperty(property_.item_type, None)
     elif property_.type_ == model.PropertyType.ENUM:
       dst_dict['enum_values'] = []
       for enum_value in property_.enum_values:
         dst_dict['enum_values'].append({'name': enum_value})
       if len(dst_dict['enum_values']) > 0:
         dst_dict['enum_values'][-1]['last'] = True
     elif property_.instance_of is not None:
       dst_dict['simple_type'] = property_.instance_of.lower()
     else:
       dst_dict['simple_type'] = property_.type_.name.lower()