Merge 200182 "Automatically detect inline-able doc in IDL files"

> Automatically detect inline-able doc in IDL files
> 
> Apply the inline_doc tag to IDL entries that are only referenced once so that they are rendered inline.
> 
> BUG=239193
> R=kalman@chromium.org
> 
> Review URL: https://codereview.chromium.org/15127007
> 
> Patch from Jared Shumway <jaredshumway94@gmail.com>.

TBR=kalman@chromium.org

Review URL: https://codereview.chromium.org/15191002

git-svn-id: svn://svn.chromium.org/chrome/branches/1453/src@200186 0039d316-1c4b-4281-b951-d872f2087c98

4 files changed, 77 insertions, 10 deletions

diff --git a/chrome/common/extensions/api/alarms.idl b/chrome/common/extensions/api/alarms.idl
index 47ccb2a..9e610ad 100644
--- a/chrome/common/extensions/api/alarms.idl
+++ b/chrome/common/extensions/api/alarms.idl
@@ -51,13 +51,11 @@ namespace alarms {
     //
     // In order to reduce the load on the user's machine, Chrome limits alarms
     // to at most once every 1 minute but may delay them an arbitrary amount
-    // more.  That is, setting <code>$ref:[alarms.AlarmCreateInfo.delayInMinutes
-    // delayInMinutes]</code> or
-    // <code>$ref:[alarms.AlarmCreateInfo.periodInMinutes
-    // periodInMinutes]</code> to less than <code>1</code> will not be honored
-    // and will cause a warning.  <code>$ref:[alarms.AlarmCreateInfo.when
-    // when]</code> can be set to less than 1 minute after "now" without
-    // warning but won't actually cause the alarm to fire for at least 1 minute.
+    // more.  That is, setting <code>delayInMinutes</code> or
+    // <code>periodInMinutes</code> to less than <code>1</code> will not be
+    // honored and will cause a warning.  <code>when</code> can be set to less
+    // than 1 minute after "now" without warning but won't actually cause the
+    // alarm to fire for at least 1 minute.
     //
     // To help you debug your app or extension, when you've loaded it unpacked,
     // there's no limit to how often the alarm can fire.
diff --git a/chrome/common/extensions/docs/server2/api_data_source.py b/chrome/common/extensions/docs/server2/api_data_source.py
index 08369f0..5d3b18c 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
+from collections import defaultdict, Mapping
 
 import compiled_file_system as compiled_fs
 from file_system import FileNotFoundError
@@ -38,6 +39,66 @@ def _RemoveNoDocs(item):
       item.remove(i)
   return False
 
+def _DetectInlineableTypes(schema):
+  """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(('value', 'choices', 'items', 'returns'))
+  refcounts = defaultdict(int)
+  # Use an explicit stack instead of recursion.
+  stack = [schema]
+
+  while stack:
+    node = stack.pop()
+    if isinstance(node, list):
+      stack.extend(node)
+    elif isinstance(node, Mapping):
+      if '$ref' in node:
+        refcounts[node['$ref']] += 1
+      stack.extend(v for k, v in node.iteritems() if k not in banned)
+
+  for type_ in schema['types']:
+    if not 'enum' in type_:
+      if refcounts[type_['id']] == 1:
+        type_['inline_doc'] = True
+
+def _InlineDocs(schema):
+  """Replace '$ref's that refer to inline_docs with the json for those docs.
+  """
+  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)
+    else:
+      types_without_inline_doc.append(type_)
+  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 _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,13 +114,16 @@ 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:
+        _DetectInlineableTypes(clean_json)
+      _InlineDocs(clean_json)
       self._namespace = model.Namespace(clean_json, clean_json['namespace'])
 
   def _FormatDescription(self, description):
@@ -356,7 +420,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 [
diff --git a/chrome/common/extensions/docs/server2/app.yaml b/chrome/common/extensions/docs/server2/app.yaml
index 3cfff26..c6c4702 100644
--- a/chrome/common/extensions/docs/server2/app.yaml
+++ b/chrome/common/extensions/docs/server2/app.yaml
@@ -1,5 +1,5 @@
 application: chrome-apps-doc
-version: 2-1-0
+version: 2-3-0
 runtime: python27
 api_version: 1
 threadsafe: false
diff --git a/chrome/common/extensions/docs/server2/cron.yaml b/chrome/common/extensions/docs/server2/cron.yaml
index c36e8c1..f899148 100644
--- a/chrome/common/extensions/docs/server2/cron.yaml
+++ b/chrome/common/extensions/docs/server2/cron.yaml
@@ -2,15 +2,19 @@ cron:
 - description: Load everything for trunk.
   url: /cron/trunk
   schedule: every 5 minutes
+  target: 2-3-0
 
 - description: Load everything for dev.
   url: /cron/dev
   schedule: every 5 minutes
+  target: 2-3-0
 
 - description: Load everything for beta.
   url: /cron/beta
   schedule: every 5 minutes
+  target: 2-3-0
 
 - description: Load everything for stable.
   url: /cron/stable
   schedule: every 5 minutes
+  target: 2-3-0