Docserver: Add 'deprecated since' message for API nodes

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

 # Copyright (c) 2012 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 copy import copy
 import logging
 import os
 import posixpath
 
 from data_source import DataSource
@@ skipping 153 matching lines @@
       callback_index = lookup_path.index('callback')
       try:
         lookup_path.pop(callback_index)
         node_availability = self._LookupNodeAvailability(lookup_path)
       finally:
         lookup_path.insert(callback_index, 'callback')
       return node_availability
     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,
                    self._CheckEventCallback,
                    self._CheckNamespacePrefix):
       node_availability = lookup(lookup_path)
       if node_availability is not None:
         return node_availability
     return None
 
@@ skipping 18 matching lines @@
       # lookup paths like
       # 'events > types > Rule > properties > tags > tagsType'.
       # These nodes are treated as properties.
       return 'properties'
     if self._lookup_path[0] == 'events':
       # HACK(ahernandez.miralles): This catches a few edge cases,
       # such as 'webviewTag > events > consolemessage > level'.
       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)

[not at google - send to devlin, 2014/07/17 20:30:06]

'return None' at end.

+
   def GetAvailability(self):
     '''Returns availability information for this node.
     '''
     if self._GetCategory() in self._ignored_categories:
       return None
     node_availability = self._LookupAvailability(self._lookup_path)
     if node_availability is None:
       logging.warning('No availability found for: %s' % self)
       return None
 
@@ skipping 325 matching lines @@
     # if they share the same 'title' attribute.
     row_titles = [row['title'] for row in intro_rows]
     for misc_row in self._GetMiscIntroRows():
       if misc_row['title'] in row_titles:
         intro_rows[row_titles.index(misc_row['title'])] = misc_row
       else:
         intro_rows.append(misc_row)
 
     return intro_rows
 
   def _GetAvailabilityTemplate(self, status=None, version=None, scheduled=None):

[not at google - send to devlin, 2014/07/17 20:30:06]

mm I didn't notice these arguments here, with the status-None, version=None,
scheduled=None stuff. I'd rather these arguments weren't here, and the place
that they're used just generate that structure itself, perhaps with a second
helper function.

     '''Returns an object that the templates use 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
+      availability_info = self._current_node.GetDeprecated()

[not at google - send to devlin, 2014/07/17 20:30:06]

please add a comment like 'Displaying deprecated status takes precedence over
when the API became stable'.

+      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
+      version = availability_info.channel_info.version
+      scheduled = availability_info.scheduled
     return {
       'partial': self._template_cache.GetFromFile(
           '%sintro_tables/%s_message.html' % (PRIVATE_TEMPLATES, status)).Get(),
       'scheduled': scheduled,
       'version': version
     }
 
   def _GetIntroDescriptionRow(self):
     ''' Generates the 'Description' row data for an API intro table.
     '''
@@ skipping 190 matching lines @@
     getter = lambda: 0
     getter.get = lambda api_name: self._GetImpl(platform, api_name).Get()
     return getter
 
   def Cron(self):
     futures = []
     for platform in GetPlatforms():
       futures += [self._GetImpl(platform, name)
           for name in self._platform_bundle.GetAPIModels(platform).GetNames()]
     return Collect(futures, except_pass=FileNotFoundError)