Automatically detect inline-able doc in IDL files

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

Index: chrome/common/extensions/docs/server2/api_data_source.py
diff --git a/chrome/common/extensions/docs/server2/api_data_source.py b/chrome/common/extensions/docs/server2/api_data_source.py
index 9695fd6dcebed8a20b8653c536f31dafa4272e1b..2f4d44ce884aa091b322aa118d0e8e19b761ab22 100644
--- a/chrome/common/extensions/docs/server2/api_data_source.py
+++ b/chrome/common/extensions/docs/server2/api_data_source.py
@@ -5,7 +5,7 @@
 import copy
 import logging
 import os
-import collections
+from collections import defaultdict, Mapping
 
 import third_party.json_schema_compiler.json_parse as json_parse
 import third_party.json_schema_compiler.model as model
@@ -28,6 +28,32 @@ def _RemoveNoDocs(item):
       item.remove(i)
   return False
 
+def _DetectInlineableIdl(schema):

[not at google - send to devlin, 2013/05/15 03:55:15]

_DetectInlinableTypes?

[jshumway, 2013/05/15 04:51:37]

Done.

+  """Look for documents that are only referenced once and mark them as inline.
+  Actual inlining is done by _InlineDocs.
+  """
+  if not schema.get('types'):
+    return
+
+  banned = frozenset(('enum', 'value', 'choices', 'items'))

[not at google - send to devlin, 2013/05/15 03:55:15]

banned sounds so mean. maybe 'exclude'.

[jshumway, 2013/05/15 04:51:37]

Done.

+  refcounts = defaultdict(int)
+  # Use an explicit stack instead of recursion.

[not at google - send to devlin, 2013/05/15 03:55:15]

comment not really necessary

[jshumway, 2013/05/15 04:51:37]

Done.

+  stack = [schema]
+
+  while stack:
+    node = stack.pop()
+    if isinstance(node, list):
+      stack.extend(node)
+    elif isinstance(node, Mapping):
+      if node.get('$ref'):

[not at google - send to devlin, 2013/05/15 03:55:15]

'$ref' in node

[jshumway, 2013/05/15 04:51:37]

Done.

+        refcounts[node['$ref']] += 1
+      for k, v in node.iteritems():
+        if k not in banned:
+          stack.append(v)

[not at google - send to devlin, 2013/05/15 03:55:15]

stack.append(v for k, v in node.iteritems() if k in not banned)

[jshumway, 2013/05/15 04:51:37]

Done.

+
+  for doc in schema['types']:

[not at google - send to devlin, 2013/05/15 03:55:15]

for type_ in ...

[jshumway, 2013/05/15 04:51:37]

Done.

+    if refcounts[doc['id']] == 1:
+      doc['inline_doc'] = True
 
 def _InlineDocs(schema):
   """Replace '$ref's that refer to inline_docs with the json for those docs.
@@ -45,7 +71,7 @@ def _InlineDocs(schema):
       inline_docs[type_['id']] = type_
       if type_.get('description'):
         del type_['description']
-      del type_['inline_doc']
+        del type_['inline_doc']

[not at google - send to devlin, 2013/05/15 03:55:15]

this doesn't look right

that said, checking for description is unnecessary too. these can be

for k in ('id', 'description', 'inline_doc'):
  type_.pop(k, None)

[jshumway, 2013/05/15 04:51:37]

Opps, that was definitely a misedit.

       del type_['id']
     else:
       types_without_inline_doc.append(type_)
@@ -55,7 +81,7 @@ def _InlineDocs(schema):
     if isinstance(node, list):
       for i in node:
         apply_inline(i)
-    elif isinstance(node, collections.Mapping):
+    elif isinstance(node, Mapping):
       ref = node.get('$ref')
       if ref and ref in inline_docs:
         node.update(inline_docs[ref])
@@ -80,13 +106,15 @@ class _JSCModel(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, ref_resolver, disable_refs):
+  def __init__(self, json, ref_resolver, disable_refs, idl=False):
     self._ref_resolver = ref_resolver
     self._disable_refs = disable_refs
     clean_json = copy.deepcopy(json)
     if _RemoveNoDocs(clean_json):
       self._namespace = None
     else:
+      if idl:
+        _DetectInlineableIdl(clean_json)
       _InlineDocs(clean_json)
       self._namespace = model.Namespace(clean_json, clean_json['namespace'])
 
@@ -380,7 +408,8 @@ class APIDataSource(object):
       return _JSCModel(
           idl_schema.IDLSchema(idl).process()[0],
           self._ref_resolver_factory.Create() if not disable_refs else None,
-          disable_refs).ToDict()
+          disable_refs,
+          idl=True).ToDict()
 
     def _GetIDLNames(self, base_dir, apis):
       return self._GetExtNames(apis, ['idl'])