Docserver: Modify doc inlining so all relevant data is present in availability_finder.py

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

 # Copyright 2013 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.
 
 from collections import defaultdict, Mapping
 import traceback
 
 from third_party.json_schema_compiler import json_parse, idl_schema, idl_parser
 
 
@@ skipping 36 matching lines @@
       if '$ref' in node:
         refcounts[node['$ref']] += 1
       stack.extend(v for k, v in node.iteritems() if k not in ignore)
 
   for type_ in schema['types']:
     if not 'noinline_doc' in type_:
       if refcounts[type_['id']] == 1:
         type_['inline_doc'] = True
 
 
-def InlineDocs(schema):
+def InlineDocs(schema, remove_nodes):
   '''Replace '$ref's that refer to inline_docs with the json for those docs.
+  If |remove_nodes| is true, then the inlined nodes are removed from the schema.
   '''
   types = schema.get('types')
   if types is None:
     return
 
   inline_docs = {}
   types_without_inline_doc = []
 
   # Gather the types with inline_doc.
   for type_ in types:
     if type_.get('inline_doc'):
       inline_docs[type_['id']] = type_
-      for k in ('description', 'id', 'inline_doc'):
-        type_.pop(k, None)
+      if remove_nodes:
+        for k in ('description', 'id', 'inline_doc'):
+          type_.pop(k, None)
     else:
       types_without_inline_doc.append(type_)
-  schema['types'] = types_without_inline_doc
+  if remove_nodes:
+    schema['types'] = types_without_inline_doc
 
   def apply_inline(node):
     if isinstance(node, list):
       for i in node:
         apply_inline(i)
     elif isinstance(node, Mapping):
       ref = node.get('$ref')
       if ref and ref in inline_docs:
         node.update(inline_docs[ref])
         del node['$ref']
       for k, v in node.iteritems():
         apply_inline(v)
 
   apply_inline(schema)
 
 
-def ProcessSchema(path, file_data, inline=False):
+def ProcessSchema(path, file_data, full_inline=False):

[not at google - send to devlin, 2014/07/15 21:12:04]

can you make this actually be explicit? "full_inline" is rather vague, perhaps
"remove_inlined_nodes" or "retain_inlined_nodes" (whichever makes more sense as
a default configuration; making it "retain" would be a backwards-compatible
change).

[not at google - send to devlin, 2014/07/15 22:43:20]

I would prefer retain_inlined_nodes actually (reverse the condition), since
typically inlining does imply not leaving the original value around.

that also gives you a chance to update the call site to explain why you're
retaining those inlined types.

come to think about it, this specifically deals with types, so
"retain_inlined_types" would be more accurate.

[ahernandez, 2014/07/15 22:49:51]

I believe this line:
https://code.google.com/p/chromium/codesearch#chromium/src/chrome/common/exte...

prevents me from reversing the condition, unless there's an easy way to get
around that.

   '''Parses |file_data| using a method determined by checking the extension of
-  the file at the given |path|. Then, trims 'nodoc' and if |inline| is given
-  and True, handles inlineable types from the parsed schema data.
+  the file at the given |path|. Then, trims 'nodoc' and if |full_inline| is
+  given and True, removes inlineable types from the parsed schema data.
   '''
   def trim_and_inline(schema, is_idl=False):
     '''Modifies an API schema in place by removing nodes that shouldn't be
     documented and inlining schema types that are only referenced once.
     '''
     if RemoveNoDocs(schema):
       # A return of True signifies that the entire schema should not be
       # documented. Otherwise, only nodes that request 'nodoc' are removed.
       return None
-    if inline:
-      if is_idl:
-        DetectInlineableTypes(schema)
-      InlineDocs(schema)
+    if is_idl:
+      DetectInlineableTypes(schema)
+    InlineDocs(schema, full_inline)
     return schema
 
   if path.endswith('.idl'):
     idl = idl_schema.IDLSchema(idl_parser.IDLParser().ParseData(file_data))
     # Wrap the result in a list so that it behaves like JSON API data.
     return [trim_and_inline(idl.process()[0], is_idl=True)]
 
   try:
     schemas = json_parse.Parse(file_data)
   except:
     raise ValueError('Cannot parse "%s" as JSON:\n%s' %
                      (path, traceback.format_exc()))
   for schema in schemas:
     # Schemas could consist of one API schema (data for a specific API file)
     # or multiple (data from extension_api.json).
     trim_and_inline(schema)
   return schemas