Docserver: Add 'deprecated since' message for API nodes

BUG=392319
NOTRY=True

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

git-svn-id: svn://svn.chromium.org/chrome/trunk/src@283899 0039d316-1c4b-4281-b951-d872f2087c98

8 files changed, 144 insertions, 105 deletions

diff --git a/chrome/common/extensions/docs/server2/api_data_source.py b/chrome/common/extensions/docs/server2/api_data_source.py
index 91dcfc3..89296fa 100644
--- a/chrome/common/extensions/docs/server2/api_data_source.py
+++ b/chrome/common/extensions/docs/server2/api_data_source.py
@@ -171,7 +171,7 @@ class _APINodeCursor(object):
     return None
 
   def _LookupAvailability(self, lookup_path):
-    '''Runs all the lookup checks on self._lookup_path and
+    '''Runs all the lookup checks on |lookup_path| and
     returns the node availability if found, None otherwise.
     '''
     for lookup in (self._LookupNodeAvailability,
@@ -210,6 +210,20 @@ class _APINodeCursor(object):
       return 'properties'
     raise AssertionError('Could not classify node %s' % self)
 
+  def GetDeprecated(self):
+    '''Returns when this node became deprecated, or None if it
+    is not deprecated.
+    '''
+    deprecated_path = self._lookup_path + ['deprecated']
+    for lookup in (self._LookupNodeAvailability,
+                   self._CheckNamespacePrefix):
+      node_availability = lookup(deprecated_path)
+      if node_availability is not None:
+        return node_availability
+    if 'callback' in self._lookup_path:
+      return self._CheckEventCallback(deprecated_path)
+    return None
+
   def GetAvailability(self):
     '''Returns availability information for this node.
     '''
@@ -555,16 +569,10 @@ class _JSCModel(object):
 
     return intro_rows
 
-  def _GetAvailabilityTemplate(self, status=None, version=None, scheduled=None):
-    '''Returns an object that the templates use to display availability
+  def _CreateAvailabilityTemplate(self, status, scheduled, version):
+    '''Returns an object suitable for use in templates to display availability
     information.
     '''
-    if status is None:
-      availability_info = self._current_node.GetAvailability()
-      if availability_info is None:
-        return None
-      status = availability_info.channel
-      version = availability_info.version
     return {
       'partial': self._template_cache.GetFromFile(
           '%sintro_tables/%s_message.html' % (PRIVATE_TEMPLATES, status)).Get(),
@@ -572,6 +580,25 @@ class _JSCModel(object):
       'version': version
     }
 
+  def _GetAvailabilityTemplate(self):
+    '''Gets availability for the current node and returns an appropriate
+    template object.
+    '''
+    # Displaying deprecated status takes precedence over when the API
+    # became stable.
+    availability_info = self._current_node.GetDeprecated()
+    if availability_info is not None:
+      status = 'deprecated'
+    else:
+      availability_info = self._current_node.GetAvailability()
+      if availability_info is None:
+        return None
+      status = availability_info.channel_info.channel
+    return self._CreateAvailabilityTemplate(
+        status,
+        availability_info.scheduled,
+        availability_info.channel_info.version)
+
   def _GetIntroDescriptionRow(self):
     ''' Generates the 'Description' row data for an API intro table.
     '''
@@ -587,18 +614,16 @@ class _JSCModel(object):
     '''
     if self._IsExperimental():
       status = 'experimental'
-      version = None
       scheduled = None
+      version = None
     else:
       status = self._availability.channel_info.channel
-      version = self._availability.channel_info.version
       scheduled = self._availability.scheduled
+      version = self._availability.channel_info.version
     return {
       'title': 'Availability',
       'content': [
-        self._GetAvailabilityTemplate(status=status,
-                                      version=version,
-                                      scheduled=scheduled)
+        self._CreateAvailabilityTemplate(status, scheduled, version)
       ]
     }
 
diff --git a/chrome/common/extensions/docs/server2/api_data_source_test.py b/chrome/common/extensions/docs/server2/api_data_source_test.py
index 6779559..011dd9b 100755
--- a/chrome/common/extensions/docs/server2/api_data_source_test.py
+++ b/chrome/common/extensions/docs/server2/api_data_source_test.py
@@ -369,6 +369,13 @@ class APIDataSourceWithNodeAvailabilityTest(unittest.TestCase):
     assertEquals('tabs.onActivated',
                  model_dict['events'][0]['availability']['version'])
 
+    # Test a node that became deprecated.
+    self.assertEquals({
+      'scheduled': None,
+      'version': 26,
+      'partial': 'handlebar chrome/common/extensions/docs/templates/' +
+          'private/intro_tables/deprecated_message.html'
+      }, model_dict['types'][2]['availability'])
 
 if __name__ == '__main__':
   unittest.main()
diff --git a/chrome/common/extensions/docs/server2/app.yaml b/chrome/common/extensions/docs/server2/app.yaml
index 8a30abf..1f72369 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: 3-31-0
+version: 3-32-0
 runtime: python27
 api_version: 1
 threadsafe: false
diff --git a/chrome/common/extensions/docs/server2/availability_finder.py b/chrome/common/extensions/docs/server2/availability_finder.py
index 63245f2..c201d0c 100644
--- a/chrome/common/extensions/docs/server2/availability_finder.py
+++ b/chrome/common/extensions/docs/server2/availability_finder.py
@@ -202,7 +202,7 @@ class AvailabilityFinder(object):
       # The _api_features.json file first appears in version 28 and should be
       # the most reliable for finding API availability.
       available_channel = _GetChannelFromAPIFeatures(api_name,
-                                                          features_bundle)
+                                                     features_bundle)
     if version >= _ORIGINAL_FEATURES_MIN_VERSION:
       # The _permission_features.json and _manifest_features.json files are
       # present in Chrome 20 and onwards. Use these if no information could be
@@ -365,7 +365,7 @@ class AvailabilityFinder(object):
                                                           file_system,
                                                           channel_info.version))
         availability_graph.Update(version_graph.Subtract(availability_graph),
-                                  annotation=channel_info)
+                                  annotation=AvailabilityInfo(channel_info))
 
       previous.stat = version_stat
       previous.graph = version_graph
diff --git a/chrome/common/extensions/docs/server2/availability_finder_test.py b/chrome/common/extensions/docs/server2/availability_finder_test.py
index 3db6ab1..860a58a 100755
--- a/chrome/common/extensions/docs/server2/availability_finder_test.py
+++ b/chrome/common/extensions/docs/server2/availability_finder_test.py
@@ -188,9 +188,16 @@ class AvailabilityFinderTest(unittest.TestCase):
               only_on='apps')
 
   def testGetAPINodeAvailability(self):
+    def assertEquals(found, channel_info, actual, scheduled=None):
+      lookup_result = api_schema_graph.LookupResult
+      if channel_info is None:
+        self.assertEquals(lookup_result(found, None), actual)
+      else:
+        self.assertEquals(lookup_result(found, AvailabilityInfo(channel_info,
+            scheduled=scheduled)), actual)
+
     for platform in GetPlatforms():
       # Allow the LookupResult constructions below to take just one line.
-      lookup_result = api_schema_graph.LookupResult
       avail_finder = self._create_availability_finder(
           self._node_fs_creator,
           self._node_fs_iterator,
@@ -198,115 +205,78 @@ class AvailabilityFinderTest(unittest.TestCase):
       tabs_graph = avail_finder.GetAPINodeAvailability('tabs')
       fake_tabs_graph = avail_finder.GetAPINodeAvailability('fakeTabs')
 
-      self.assertEquals(
-          lookup_result(True, self._branch_utility.GetChannelInfo('trunk')),
-          tabs_graph.Lookup('tabs', 'properties',
-                                    'fakeTabsProperty3'))
-      self.assertEquals(
-          lookup_result(True, self._branch_utility.GetChannelInfo('dev')),
-          tabs_graph.Lookup('tabs', 'events', 'onActivated',
-                                    'parameters', 'activeInfo', 'properties',
-                                    'windowId'))
-      self.assertEquals(
-          lookup_result(True, self._branch_utility.GetChannelInfo('dev')),
-          tabs_graph.Lookup('tabs', 'events', 'onUpdated', 'parameters',
-                                    'tab'))
-      self.assertEquals(
-          lookup_result(True, self._branch_utility.GetChannelInfo('beta')),
-          tabs_graph.Lookup('tabs', 'events','onActivated'))
-      self.assertEquals(
-          lookup_result(True, self._branch_utility.GetChannelInfo('beta')),
-          tabs_graph.Lookup('tabs', 'functions', 'get', 'parameters',
-                                    'tabId'))
-      self.assertEquals(
-          lookup_result(True, self._branch_utility.GetChannelInfo('stable')),
-          tabs_graph.Lookup('tabs', 'types', 'InjectDetails',
-                                    'properties', 'code'))
-      self.assertEquals(
-          lookup_result(True, self._branch_utility.GetChannelInfo('stable')),
-          tabs_graph.Lookup('tabs', 'types', 'InjectDetails',
-                                    'properties', 'file'))
-      self.assertEquals(
-          lookup_result(True, self._branch_utility.GetStableChannelInfo(25)),
+      assertEquals(True, self._branch_utility.GetChannelInfo('trunk'),
+          tabs_graph.Lookup('tabs', 'properties', 'fakeTabsProperty3'))
+      assertEquals(True, self._branch_utility.GetChannelInfo('dev'),
+          tabs_graph.Lookup('tabs', 'events', 'onActivated', 'parameters',
+              'activeInfo', 'properties', 'windowId'))
+      assertEquals(True, self._branch_utility.GetChannelInfo('dev'),
+          tabs_graph.Lookup('tabs', 'events', 'onUpdated', 'parameters', 'tab'))
+      assertEquals(True, self._branch_utility.GetChannelInfo('beta'),
+          tabs_graph.Lookup('tabs', 'events', 'onActivated'))
+      assertEquals(True, self._branch_utility.GetChannelInfo('beta'),
+          tabs_graph.Lookup('tabs', 'functions', 'get', 'parameters', 'tabId'))
+      assertEquals(True, self._branch_utility.GetChannelInfo('stable'),
+          tabs_graph.Lookup('tabs', 'types', 'InjectDetails', 'properties',
+              'code'))
+      assertEquals(True, self._branch_utility.GetChannelInfo('stable'),
+          tabs_graph.Lookup('tabs', 'types', 'InjectDetails', 'properties',
+              'file'))
+      assertEquals(True, self._branch_utility.GetStableChannelInfo(25),
           tabs_graph.Lookup('tabs', 'types', 'InjectDetails'))
 
       # Test inlined type.
-      self.assertEquals(
-          lookup_result(True, self._branch_utility.GetChannelInfo('trunk')),
+      assertEquals(True, self._branch_utility.GetChannelInfo('trunk'),
           tabs_graph.Lookup('tabs', 'types', 'InlinedType'))
 
       # Test implicitly inlined type.
-      self.assertEquals(
-          lookup_result(True, self._branch_utility.GetStableChannelInfo(25)),
+      assertEquals(True, self._branch_utility.GetStableChannelInfo(25),
           fake_tabs_graph.Lookup('fakeTabs', 'types',
-                                 'WasImplicitlyInlinedType'))
+              'WasImplicitlyInlinedType'))
 
       # Nothing new in version 24 or 23.
 
-      self.assertEquals(
-          lookup_result(True, self._branch_utility.GetStableChannelInfo(22)),
-          tabs_graph.Lookup('tabs', 'types', 'Tab', 'properties',
-                                    'windowId'))
-      self.assertEquals(
-          lookup_result(True, self._branch_utility.GetStableChannelInfo(21)),
-          tabs_graph.Lookup('tabs', 'types', 'Tab', 'properties',
-                                    'selected'))
+      assertEquals(True, self._branch_utility.GetStableChannelInfo(22),
+          tabs_graph.Lookup('tabs', 'types', 'Tab', 'properties', 'windowId'))
+      assertEquals(True, self._branch_utility.GetStableChannelInfo(21),
+          tabs_graph.Lookup('tabs', 'types', 'Tab', 'properties', 'selected'))
 
       # Nothing new in version 20.
 
-      self.assertEquals(
-          lookup_result(True, self._branch_utility.GetStableChannelInfo(19)),
+      assertEquals(True, self._branch_utility.GetStableChannelInfo(19),
           tabs_graph.Lookup('tabs', 'functions', 'getCurrent'))
-      self.assertEquals(
-          lookup_result(True, self._branch_utility.GetStableChannelInfo(18)),
-          tabs_graph.Lookup('tabs', 'types', 'Tab', 'properties',
-                                    'index'))
-      self.assertEquals(
-          lookup_result(True, self._branch_utility.GetStableChannelInfo(17)),
+      assertEquals(True, self._branch_utility.GetStableChannelInfo(18),
+          tabs_graph.Lookup('tabs', 'types', 'Tab', 'properties', 'index'))
+      assertEquals(True, self._branch_utility.GetStableChannelInfo(17),
           tabs_graph.Lookup('tabs', 'events', 'onUpdated', 'parameters',
-                                    'changeInfo'))
+              'changeInfo'))
 
       # Nothing new in version 16.
 
-      self.assertEquals(
-          lookup_result(True, self._branch_utility.GetStableChannelInfo(15)),
-          tabs_graph.Lookup('tabs', 'properties',
-                                    'fakeTabsProperty2'))
+      assertEquals(True, self._branch_utility.GetStableChannelInfo(15),
+          tabs_graph.Lookup('tabs', 'properties', 'fakeTabsProperty2'))
 
       # Everything else is available at the API's release, version 14 here.
-      self.assertEquals(
-          lookup_result(True, self._branch_utility.GetStableChannelInfo(14)),
+      assertEquals(True, self._branch_utility.GetStableChannelInfo(14),
           tabs_graph.Lookup('tabs', 'types', 'Tab'))
-      self.assertEquals(
-          lookup_result(True, self._branch_utility.GetStableChannelInfo(14)),
-          tabs_graph.Lookup('tabs', 'types', 'Tab',
-                                    'properties', 'url'))
-      self.assertEquals(
-          lookup_result(True, self._branch_utility.GetStableChannelInfo(14)),
-          tabs_graph.Lookup('tabs', 'properties',
-                                    'fakeTabsProperty1'))
-      self.assertEquals(
-          lookup_result(True, self._branch_utility.GetStableChannelInfo(14)),
+      assertEquals(True, self._branch_utility.GetStableChannelInfo(14),
+          tabs_graph.Lookup('tabs', 'types', 'Tab', 'properties', 'url'))
+      assertEquals(True, self._branch_utility.GetStableChannelInfo(14),
+          tabs_graph.Lookup('tabs', 'properties', 'fakeTabsProperty1'))
+      assertEquals(True, self._branch_utility.GetStableChannelInfo(14),
           tabs_graph.Lookup('tabs', 'functions', 'get', 'parameters',
-                                    'callback'))
-      self.assertEquals(
-          lookup_result(True, self._branch_utility.GetStableChannelInfo(14)),
+              'callback'))
+      assertEquals(True, self._branch_utility.GetStableChannelInfo(14),
           tabs_graph.Lookup('tabs', 'events', 'onUpdated'))
 
       # Test things that aren't available.
-      self.assertEqual(lookup_result(False, None),
-                       tabs_graph.Lookup('tabs', 'types',
-                                                 'UpdateInfo'))
-      self.assertEqual(lookup_result(False, None),
-                       tabs_graph.Lookup('tabs', 'functions', 'get',
-                                                 'parameters', 'callback',
-                                                 'parameters', 'tab', 'id'))
-      self.assertEqual(lookup_result(False, None),
-                       tabs_graph.Lookup('functions'))
-      self.assertEqual(lookup_result(False, None),
-                       tabs_graph.Lookup('events', 'onActivated',
-                                                 'parameters', 'activeInfo',
-                                                 'tabId'))
+      assertEquals(False, None, tabs_graph.Lookup('tabs', 'types',
+          'UpdateInfo'))
+      assertEquals(False, None, tabs_graph.Lookup('tabs', 'functions', 'get',
+          'parameters', 'callback', 'parameters', 'tab', 'id'))
+      assertEquals(False, None, tabs_graph.Lookup('functions'))
+      assertEquals(False, None, tabs_graph.Lookup('events', 'onActivated',
+          'parameters', 'activeInfo', 'tabId'))
 
 
 if __name__ == '__main__':
diff --git a/chrome/common/extensions/docs/server2/cron.yaml b/chrome/common/extensions/docs/server2/cron.yaml
index 4dae3e4..0aa1c2a 100644
--- a/chrome/common/extensions/docs/server2/cron.yaml
+++ b/chrome/common/extensions/docs/server2/cron.yaml
@@ -2,4 +2,4 @@ cron:
 - description: Repopulates all cached data.
   url: /_cron
   schedule: every 5 minutes
-  target: 3-31-0
+  target: 3-32-0
diff --git a/chrome/common/extensions/docs/server2/test_data/object_level_availability/tabs.py b/chrome/common/extensions/docs/server2/test_data/object_level_availability/tabs.py
index f5456d7..2c12521 100644
--- a/chrome/common/extensions/docs/server2/test_data/object_level_availability/tabs.py
+++ b/chrome/common/extensions/docs/server2/test_data/object_level_availability/tabs.py
@@ -42,7 +42,11 @@ TABS_SCHEMA_BRANCHES = MoveAllTo(CHROME_EXTENSIONS, {
       }
     },
     'api': {
-      '_api_features.json': '{}',
+      '_api_features.json': json.dumps({
+        'tabs.scheduledFunc': {
+          'channel': 'stable'
+        }
+      }),
       '_manifest_features.json': '{}',
       '_permission_features.json': '{}',
       'fake_tabs.idl': FAKE_TABS_IDL,
@@ -89,6 +93,11 @@ TABS_SCHEMA_BRANCHES = MoveAllTo(CHROME_EXTENSIONS, {
                 'type':'any'
               }
             }
+          },
+          {
+            'id': 'DeprecatedType',
+            'type': 'any',
+            'deprecated': 'This is deprecated'
           }
         ],
         'properties': {
@@ -136,6 +145,10 @@ TABS_SCHEMA_BRANCHES = MoveAllTo(CHROME_EXTENSIONS, {
                 'type': 'any'
               }
             ]
+          },
+          {
+            'name': 'scheduledFunc',
+            'parameters': []
           }
         ],
         'events': [
@@ -189,7 +202,11 @@ TABS_SCHEMA_BRANCHES = MoveAllTo(CHROME_EXTENSIONS, {
   },
   '1500': {
     'api': {
-      '_api_features.json': "{}",
+      '_api_features.json': json.dumps({
+        'tabs.scheduledFunc': {
+          'channel': 'stable'
+        }
+      }),
       '_manifest_features.json': "{}",
       '_permission_features.json': "{}",
       'fake_tabs.idl': FAKE_TABS_IDL,
@@ -213,6 +230,10 @@ TABS_SCHEMA_BRANCHES = MoveAllTo(CHROME_EXTENSIONS, {
               'code': {},
               'file': {}
             }
+          },
+          {
+            'id': 'DeprecatedType',
+            'deprecated': 'This is deprecated'
           }
         ],
         'properties': {
@@ -248,6 +269,10 @@ TABS_SCHEMA_BRANCHES = MoveAllTo(CHROME_EXTENSIONS, {
                 'name': 'tabId'
               }
             ]
+          },
+          {
+            'name': 'scheduledFunc',
+            'parameters': []
           }
         ],
         'events': [
@@ -311,6 +336,10 @@ TABS_SCHEMA_BRANCHES = MoveAllTo(CHROME_EXTENSIONS, {
               'code': {},
               'file': {}
             }
+          },
+          {
+            'id': 'DeprecatedType',
+            'deprecated': 'This is deprecated'
           }
         ],
         'properties': {
@@ -404,6 +433,10 @@ TABS_SCHEMA_BRANCHES = MoveAllTo(CHROME_EXTENSIONS, {
               'code': {},
               'file': {}
             }
+          },
+          {
+            'id': 'DeprecatedType',
+            'deprecated': 'This is deprecated'
           }
         ],
         'properties': {
@@ -481,6 +514,9 @@ TABS_SCHEMA_BRANCHES = MoveAllTo(CHROME_EXTENSIONS, {
             'properties': {
               'allFrames': {}
             }
+          },
+          {
+            'id': 'DeprecatedType',
           }
         ],
         'properties': {
diff --git a/chrome/common/extensions/docs/templates/private/intro_tables/deprecated_message.html b/chrome/common/extensions/docs/templates/private/intro_tables/deprecated_message.html
new file mode 100644
index 0000000..6501c72
--- /dev/null
+++ b/chrome/common/extensions/docs/templates/private/intro_tables/deprecated_message.html
@@ -0,0 +1 @@
+Deprecated since Chrome {{content.version}}.