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
+    # Check for this before calling CheckEventCallback to avoid
+    # unnecessary AssertionErrors.

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

comment is unnecessary, code is clear enough

+    if 'callback' in self._lookup_path:
+      return self._CheckEventCallback(deprecated_path)
+
   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:
       if not IsReleaseServer():
         # Bad, and happens a lot :(
         logging.warning('No availability found for: %s' % self)
       return None
 
+    # Check this before checking parent availability; we always want

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

I'd rather that the callers worry about this rather than GetAvailability(). See
below.

+    # to see when an API became deprecated.
+    deprecated_availability = self.GetDeprecated()
+    if deprecated_availability is not None:
+      # The same annotation object is used for multiple nodes.
+      deprecated_info = copy(deprecated_availability)
+      deprecated_info.channel = 'deprecated'
+      return deprecated_info
+
     parent_node_availability = self._LookupAvailability(self._GetParentPath())
     # If the parent node availability couldn't be found, something
     # is very wrong.
     assert parent_node_availability is not None
 
     # Only render this node's availability if it differs from the parent
     # node's availability.
     if node_availability == parent_node_availability:
       return None
     return node_availability
@@ skipping 315 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/15 21:51:15]

a thought: does the function/event level availability take into account / set
scheduled? because the deprecated template should as well, and it should always
have a scheduled time (I don't think it's possible otherwise). I mention this
because while we might render availability as "available in dev channel
(scheduled for chrome 38)" we shouldn't say "deprecated in dev channel" we
should say "deprecated in chrome 38".

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

It can't say "deprecated in dev channel"; deprecated_message.html only uses the
ChannelInfo.version attribute, which is always a number.

Deprecated nodes can be scheduled?

     '''Returns an object that the templates use to display availability
     information.
     '''
     if status is None:
       availability_info = self._current_node.GetAvailability()

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

put that logic down here:

availability_info = self._current_node.GetDeprecated()
if availability_info is None:
  availability_info = self._current_node.GetAvailability()
...

or whatever.

       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(),
       'scheduled': scheduled,
       'version': version
     }
@@ skipping 194 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)