Generating annotations from DOM triage list.

tools/dom/scripts/dartmetadata.py

 #!/usr/bin/python
 # Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file
 # for details. All rights reserved. Use of this source code is governed by a
 # BSD-style license that can be found in the LICENSE file.
 
 """This module provides shared functionality to provide Dart metadata for
 DOM APIs.
 """
 
 import copy
@@ skipping 374 matching lines @@
   'XMLHttpRequest.overrideMimeType': _no_ie_annotations,
   'XMLHttpRequest.response': _all_but_ie9_annotations,
   'XMLHttpRequestProgressEvent': _webkit_experimental_annotations,
   'XSLTProcessor': [
     "@SupportedBrowser(SupportedBrowser.CHROME)",
     "@SupportedBrowser(SupportedBrowser.FIREFOX)",
     "@SupportedBrowser(SupportedBrowser.SAFARI)",
   ],
 })
 
+# TODO(blois): minimize noise and enable by default.
+_monitor_type_metadata = False
 
 class DartMetadata(object):
   def __init__(self, api_status_path, doc_comments_path):
     self._api_status_path = api_status_path
     status_file = open(self._api_status_path, 'r+')
     self._types = json.load(status_file)
     status_file.close()
 
     comments_file = open(doc_comments_path, 'r+')
     self._doc_comments = json.load(comments_file)
     comments_file.close()
 
+    if _monitor_type_metadata:
+      monitored_interfaces = {}
+      for interface_id, interface_data in self._types.iteritems():
+        monitored_interface = interface_data.copy()
+        monitored_interface['members'] = monitored.Dict(
+            'dartmetadata.%s' % interface_id, interface_data['members'])
+
+        monitored_interfaces[interface_id] = monitored_interface
+
+      self._monitored_types = monitored.Dict('dartmetadata._monitored_types',
+          monitored_interfaces)
+    else:
+      self._monitored_types = self._types
+
   def GetFormattedMetadata(self, library_name, interface, member_id=None,
       indentation=''):
     """ Gets all comments and annotations for an interface or member.
     """
     return self.FormatMetadata(
         self.GetMetadata(library_name, interface, member_id),
         indentation)
 
   def GetMetadata(self, library_name, interface,
         member_name=None, source_member_name=None):
@@ skipping 49 matching lines @@
         interface.id not in html_interface_renames):
       annotations.extend(_webkit_experimental_annotations)
 
     if (member_name and member_name.startswith('webkit') and
         key not in renamed_html_members):
       annotations.extend(_webkit_experimental_annotations)
 
     if source_member_name:
       member_name = source_member_name
 
-    # TODO(blois): Emit support level annotations
-    self._GetSupportLevelAnnotation(interface.id, member_name)
+    support_annotations = self._GetSupportLevelAnnotations(
+        interface.id, member_name)
+
+    for annotation in support_annotations:
+      if annotation not in annotations:
+        annotations.append(annotation)
 
     return annotations
 
   def _GetComments(self, library_name, interface, member_name=None):
     """ Gets all comments for the interface or member and returns a list. """
 
     # Add documentation from JSON.
     comments = []
     library_name = 'dart.dom.%s' % library_name
     if library_name in self._doc_comments:
@@ skipping 39 matching lines @@
       if ann2:
         return ann2 + ann1
       return ann1
 
     ann2 = _dart2js_annotations.get('-' + idl_type)
     if ann2:
       return ann2
     ann2 = _dart2js_annotations.get(idl_type)
     return ann2
 
-  def _GetSupportLevel(self, interface_id, member_id=None):
+  def _GetSupportInfo(self, interface_id, member_id=None):
     """ Looks up the interface or member in the DOM status list and returns the
     support level for it.
     """
-    if interface_id in self._types:
-      type_info = self._types[interface_id]
+    if interface_id in self._monitored_types:
+      type_info = self._monitored_types[interface_id]
     else:
       type_info = {
         'members': {},
         'support_level': 'untriaged',
       }
       self._types[interface_id] = type_info
 
     if not member_id:
-      return type_info.get('support_level')
+      return type_info
 
     members = type_info['members']
 
     if member_id in members:
       member_info = members[member_id]
     else:
       if member_id == interface_id:
         member_info = {}
       else:
         member_info = {'support_level': 'untriaged'}
       members[member_id] = member_info
 
-    support_level = member_info.get('support_level')
-    # If unset then it inherits from the type.
-    if not support_level:
-      support_level = type_info.get('support_level')
-    return support_level
+    return member_info
 
-  def _GetSupportLevelAnnotation(self, interface_id, member_id=None):
-    support_level = self._GetSupportLevel(interface_id, member_id)
+  def _GetSupportLevelAnnotations(self, interface_id, member_id=None):
+    """ Gets annotations for API support status.
+    """
+    support_info = self._GetSupportInfo(interface_id, member_id)
 
-    if support_level == 'untriaged':
-      return '@Experimental'
+    dart_action = support_info.get('dart_action')
+    support_level = support_info.get('support_level')
+    comment = support_info.get('comment')
+    annotations = []
+    # TODO(blois): should add an annotation for the comment, but keeping out
+    # to keep the initial diff a bit more localized.
+    #if comment:
+    #  annotations.append('// %s' % comment)
+
+    if dart_action:
+      if dart_action == 'unstable':
+        annotations.append('@Unstable')
+      elif dart_action == 'experimental':
+        if comment:
+          annotations.append('// %s' % comment)
+        annotations.append('@Experimental // %s' % support_level)
+      elif dart_action == 'suppress':
+        if comment:
+          annotations.append('// %s' % comment)
+        annotations.append('@deprecated // %s' % support_level)
+        # TODO (blois): suppress generation of these APIs as a separate CL.
+        pass
+      else:
+        _logger.warn('Unknown dart_action - %s:%s' % (interface_id, member_id))
+    elif support_level == 'untriaged':
+      annotations.append('@Experimental // untriaged')
     elif support_level == 'experimental':
-      return '@Experimental'
+      if comment:
+        annotations.append('// %s' % comment)
+      annotations.append('@Experimental')
     elif support_level == 'nonstandard':
-      return '@Experimental'
+      if comment:
+        annotations.append('// %s' % comment)
+      annotations.append('@Experimental // non-standard')
     elif support_level == 'stable':
-      return
+      pass
     elif support_level == 'deprecated':
-      return '@Deprecated'
+      if comment:
+        annotations.append('// %s' % comment)
+      annotations.append('@Deprecated')
+    elif support_level is None:
+      pass
     else:
       _logger.warn('Unknown support_level - %s:%s' % (interface_id, member_id))
 
+    return annotations
+
   def Flush(self):
     json_file = open(self._api_status_path, 'w+')
     json.dump(self._types, json_file, indent=2, separators=(',', ': '), sort_keys=True)
     json_file.close()