Extensions Docs Server: HandlebarDictGenerator

chrome/common/extensions/docs/server2/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 os
+
+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
+
+class DictGenerator(object):
+  """Uses a Model from the JSON Schema Compiler and generates a dict that
+  a Handlebar template can use for a data source.
+  """
+  def __init__(self, json):
+    _RemoveNoDocs(json)
+    self._namespace = model.Namespace(json, json['namespace'])
+
+  def _GenerateType(self, t):

[not at google - send to devlin, 2012/06/19 20:33:10]

generally I prefer to list functions top-down. So the public methods like
Generate up the top, then _GenerateTypes below that, _GenerateType below that,
etc.

[cduvall, 2012/06/19 22:21:02]

Done.

+    type_dict = {}
+    type_dict['name'] = t.name

[not at google - send to devlin, 2012/06/19 20:33:10]

"t" -> "type_"

I'd have called "type_dict" just "dict" but no biggie. Also you can initialize
this dict a bit up-front like

type_dict = {
  'name': type_.name,
  'type': type_.type_
}

same for a lot of the things in this file.

[cduvall, 2012/06/19 22:21:02]

Done.

+    if t.description:
+      type_dict['description'] = t.description
+    type_dict['properties'] = self._GenerateProperties(t.properties)
+    if getattr(t, 'functions', None):
+      type_dict['functions'] = self._GenerateFunctions(t.functions)
+    type_dict['type'] = t.type_.name
+    if getattr(t, 'item_type', None):
+      type_dict['item_type'] = self._GenerateType(t.item_type)

[not at google - send to devlin, 2012/06/19 20:33:10]

It looks like model.py normalises this and always sets properties/functions so
you don't need to check with getattr.

(in fact needing to use getattr everywhere would be a failing of a model type)

[cduvall, 2012/06/19 22:21:02]

Done.

+    return type_dict
+
+  def _GenerateTypes(self, types):
+    if len(types) == 0:
+      return None

[not at google - send to devlin, 2012/06/19 20:33:10]

hmmmm I'm not sure whether no-types should be normalised as a empty list or as
None (ditto properties etc). I'd probably say empty-list is probably less to
think about but it's much of a muchness. 

[cduvall, 2012/06/19 22:21:02]

Done.

+    types_list = []
+    for t in types:
+      types_list.append(self._GenerateType(types[t]))

[not at google - send to devlin, 2012/06/19 20:33:10]

try to have names like "type_name" rather than "t".

[cduvall, 2012/06/19 22:21:02]

Done.

+    return types_list
+
+  def _GenerateCallback(self, c):
+    callback_dict = {}
+    callback_dict['name'] = 'callback'
+    if len(c.params) != 0:

[not at google - send to devlin, 2012/06/19 20:33:10]

 > 0

[cduvall, 2012/06/19 22:21:02]

I just made the params empty if it doesn't have them.

+      callback_dict['parameters'] = []
+      for param in c.params:
+        callback_dict['parameters'].append(self._GenerateProperty(param))
+    return callback_dict
+
+  def _GenerateFunction(self, f):
+    function_dict = {}
+    function_dict['name'] = f.name
+    if f.description:
+      function_dict['description'] = f.description
+    if len(f.params) != 0:
+      function_dict['parameters'] = []
+      for param in f.params:
+        function_dict['parameters'].append(self._GenerateProperty(param))
+    if f.callback:
+      function_dict['callback'] = self._GenerateCallback(f.callback)
+    return function_dict
+
+  def _GenerateFunctions(self, functions):
+    if len(functions) == 0:
+      return None
+    functions_list = []
+    for f in functions:
+      functions_list.append(self._GenerateFunction(functions[f]))
+    return functions_list
+
+  def _GenerateProperty(self, p):
+    property_dict = {}
+    property_dict['name'] = p.name
+    property_dict['optional'] = p.optional
+    if p.description:
+      property_dict['description'] = p.description
+    property_dict['type'] = p.type_.name
+    if getattr(p, 'choices', None):
+      property_dict['choices'] = []
+      for c in p.choices:
+        property_dict['choices'].append(self._GenerateProperty(p.choices[c]))
+    if getattr(p, 'ref_type', None):
+      property_dict['ref_type'] = p.ref_type
+    if getattr(p, 'item_type', None):
+      property_dict['item_type'] = self._GenerateType(p.item_type)
+    property_dict['properties'] = self._GenerateProperties(p.properties)
+    return property_dict
+
+  def _GenerateProperties(self, properties):
+    if len(properties) == 0:
+      return None
+    properties_list = []
+    for p in properties:
+      properties_list.append(self._GenerateProperty(properties[p]))
+    return properties_list
+
+  def Generate(self):
+    d = {}
+    d['name'] = self._namespace.name
+    d['types'] = self._GenerateTypes(self._namespace.types)
+    d['functions'] = self._GenerateFunctions(self._namespace.functions)
+    d['properties'] = self._GenerateProperties(self._namespace.properties)

[not at google - send to devlin, 2012/06/19 20:33:10]

return {
  'name': self._namespace.name,
  'types': self._GenerateTypes(..)
  ..
}

?

[cduvall, 2012/06/19 22:21:02]

Done.

+    return d