Inline docs render properly in extensions doc server.

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 9afa3dd92d6ed518ed7082746c72493fa9cc7f75..443daf8045c78b483b0255fdf332972e11c8db74 100644
--- a/chrome/common/extensions/docs/server2/api_data_source.py
+++ b/chrome/common/extensions/docs/server2/api_data_source.py
@@ -5,6 +5,7 @@
 import copy
 import logging
 import os
+import collections
 
 import third_party.json_schema_compiler.json_parse as json_parse
 import third_party.json_schema_compiler.model as model
@@ -13,7 +14,7 @@ import third_party.json_schema_compiler.idl_parser as idl_parser
 
 # Increment this if the data model changes for APIDataSource.
 # This would include changes to model.py in json_schema_compiler!
-_VERSION = 17
+_VERSION = 18
 
 def _RemoveNoDocs(item):
   if json_parse.IsDict(item):
@@ -31,6 +32,47 @@ def _RemoveNoDocs(item):
       item.remove(i)
   return False
 
+
+def _InlineDocs(schema):
+  """Replace '$ref's that refer to inline_docs with the json for those docs.
+  """
+  types = schema.get('types')
+  inline_docs = {}
+  types_without_inline_doc = []
+
+  if types is None:
+    return

[not at google - send to devlin, 2013/04/24 19:36:11]

move this up under where types is assigned

[jshumway, 2013/04/25 00:06:58]

done

+  # Gather the types with inline_doc.
+  for type_ in types:
+    if type_.get('inline_doc'):
+      inline_docs[type_['id']] = type_
+      del type_['inline_doc']
+      del type_['id']
+    else:
+      types_without_inline_doc.append(type_)
+  schema['types'] = types_without_inline_doc
+
+  def apply_inline(node):
+    ref = node.get('$ref')
+    if ref and ref in inline_docs:
+      if node.get('description') and inline_docs[ref].get('description'):
+        # In the IDL files, an enum's description field is often inline html
+        # describing the enum's possible values. To prevent this description
+        # overriding the inline ref's description, special action is taken.
+        node['extended_description'] = inline_docs[ref].pop('description')

[not at google - send to devlin, 2013/04/24 19:36:11]

Hm, very interesting. I hadn't thought of that.

Now I have, and I have a proposal. Let's just ignore the inlined type's
description. Inlining the docs implies that the type isn't valuable as an entity
by itself, which implies that any comment made as though it were isn't valuable
either.

The bonus of that is that we don't need extended_description. 

[jshumway, 2013/04/25 00:06:58]

Okay, I removed both inline_type and extended_description.

+      node.update(inline_docs[ref])
+      node['inline_type'] = node.pop('$ref')
+
+    for k, v in node.iteritems():
+      if isinstance(v, collections.Mapping):
+        apply_inline(v)
+      elif isinstance(v, list):
+        for i in v:
+          if isinstance(i, collections.Mapping):
+            apply_inline(i)
+
+  apply_inline(schema)
+
 def _CreateId(node, prefix):
   if node.parent is not None and not isinstance(node.parent, model.Namespace):
     return '-'.join([prefix, node.parent.simple_name, node.simple_name])
@@ -53,6 +95,7 @@ class _JSCModel(object):
     if _RemoveNoDocs(clean_json):
       self._namespace = None
     else:
+      _InlineDocs(clean_json)
       self._namespace = model.Namespace(clean_json, clean_json['namespace'])
 
   def _FormatDescription(self, description):
@@ -181,8 +224,10 @@ class _JSCModel(object):
 
     property_dict = {
       'name': property_.simple_name,
+      'inline_type': property_.inline_type,
       'optional': property_.optional,
       'description': self._FormatDescription(property_.description),
+      'extended_description': property_.extended_description,
       'properties': self._GenerateProperties(type_.properties),
       'functions': self._GenerateFunctions(type_.functions),
       'parameters': [],