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):

[Andrei Mouravski, 2013/05/22 10:07:00]

Please add doc comments to this method.

[blois, 2013/05/22 17:59:10]

Done.

+    support_info = self._GetSupportInfo(interface_id, member_id)
 
-    if support_level == 'untriaged':
-      return '@Experimental'
+    dart_action = support_info.get('dart_action')

[Andrei Mouravski, 2013/05/22 10:07:00]

What is the difference between dart_action and support_level?

[blois, 2013/05/22 17:59:10]

support_level indicates the official status of the API (according to W3C or
WhatWG) and should be something that we could publish and get feedback on
completely independent of Dart.

dart_action is Dart's biased treatment of the API.

+    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:

[Andrei Mouravski, 2013/05/22 10:07:00]

There's a lot of duplication of code here.

Assuming everything has a support level, I would write this as:

levels = {
  'unstable' : '@Unstable',
  'experimental' : '@Experimental',
  'suppress' : '@deprecated',
  'untriaged' : '@Experimental // untriaged',
  'nonstandard' : '@Experimental // non-standard'
}

for level, value in levels:
  if level in [dart_action, support_level]:
    if comment:
      annotations.append('// %s' % comment)
    support_string = value
    if dart_action:
      support_string.append(' // %s' % support_level)
    annotations.append('%s%s' % value, support_string)

[blois, 2013/05/22 17:59:10]

dart_actions override support_level. In later CLs, 'suppress' APIs will actually
be suppressed.

Comments were only generated for ease of review, but should be removed to
annotation (see TODO).

Unless there are bugs with this code, I'd prefer to leave as-is, since it's
still in flux.

Basically this CL is the first one actually applying the metadata and I'm trying
to keep the generated results easy to review. Later CLs need to change how we
apply the metadata, but won't require that all of the metadata be re-reviewed.


On 2013/05/22 10:07:00, Andrei Mouravski wrote:

+      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()