Refactoring DOM annotations and comment generation, adding DOM API triage list

tools/dom/scripts/htmldartgenerator.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 for the system to generate
 dart:html APIs from the IDL database."""
 
 import emitter
 from generator import AnalyzeOperation, ConstantOutputOrder, \
     DartDomNameOfAttribute, FindMatchingAttribute, IsDartCollectionType, \
-    IsPureInterface, TypeOrNothing, GetAnnotationsAndComments, \
-    FormatAnnotationsAndComments, ConvertToFuture, GetCallbackInfo
+    IsPureInterface, TypeOrNothing, ConvertToFuture, GetCallbackInfo
 from htmlrenamer import convert_to_future_members
 
 # Types that are accessible cross-frame in a limited fashion.
 # In these cases, the base type (e.g., WindowBase) provides restricted access
 # while the subtype (e.g., Window) provides full access to the
 # corresponding objects if there are from the same frame.
 _secure_base_types = {
   'Window': 'WindowBase',
   'Location': 'LocationBase',
   'History': 'HistoryBase',
 }
 
 _custom_factories = [
   'Notification',
   'EventSource',
 ]
 
 class HtmlDartGenerator(object):
   def __init__(self, interface, options):
     self._database = options.database
     self._interface = interface
     self._type_registry = options.type_registry
     self._interface_type_info = self._type_registry.TypeInfo(self._interface.id)
     self._renamer = options.renamer
+    self._metadata = options.metadata
     self._library_name = self._renamer.GetLibraryName(self._interface)
 
   def EmitSupportCheck(self):
     if self.HasSupportCheck():
       check = self.GetSupportCheck()
       if type(check) != tuple:
         signature = 'get supported'
       else:
         signature = check[0]
         check = check[1]
@@ skipping 290 matching lines @@
     """
     for constructor_info in constructors:
       self._AddConstructor(
           constructor_info, factory_name, factory_constructor_name)
 
   def _AddConstructor(self,
       constructor_info, factory_name, factory_constructor_name):
     if self.GenerateCustomFactory(constructor_info):
       return
 
-    annotations = FormatAnnotationsAndComments(
-        GetAnnotationsAndComments(self._library_name, self._interface.id,
-                                  self._interface.id), '  ')
+    metadata = self._metadata.GetFormattedMetadata(
+        self._library_name, self._interface.id, self._interface.id, '  ')
 
     if not factory_constructor_name:
       factory_constructor_name = '_create'
       factory_parameters = constructor_info.ParametersAsArgumentList()
       has_factory_provider = True
     else:
       factory_parameters = ', '.join(constructor_info.factory_parameters)
       has_factory_provider = False
 
     if constructor_info.pure_dart_constructor:
       # TODO(antonm): use common dispatcher generation for this case as well.
       has_optional = any(param_info.is_optional
           for param_info in constructor_info.param_infos)
 
       if not has_optional:
         self._members_emitter.Emit(
-            '\n  $(ANNOTATIONS)'
+            '\n  $(METADATA)'
             'factory $CTOR($PARAMS) => '
             '$FACTORY.$CTOR_FACTORY_NAME($FACTORY_PARAMS);\n',
             CTOR=constructor_info._ConstructorFullName(self._DartType),
             PARAMS=constructor_info.ParametersDeclaration(self._DartType),
             FACTORY=factory_name,
-            ANNOTATIONS=annotations,
+            METADATA=metadata,
             CTOR_FACTORY_NAME=factory_constructor_name,
             FACTORY_PARAMS=factory_parameters)
       else:
         if has_factory_provider:
           dispatcher_emitter = self._members_emitter.Emit(
-              '\n  $(ANNOTATIONS)'
+              '\n  $(METADATA)'
               'factory $CTOR($PARAMS) {\n'
               '$!DISPATCHER'
               '    return $FACTORY._create($FACTORY_PARAMS);\n'
               '  }\n',
               CTOR=constructor_info._ConstructorFullName(self._DartType),
               PARAMS=constructor_info.ParametersDeclaration(self._DartType),
               FACTORY=factory_name,
-              ANNOTATIONS=annotations,
+              METADATA=metadata,
               FACTORY_PARAMS=constructor_info.ParametersAsArgumentList())
 
           for index, param_info in enumerate(constructor_info.param_infos):
             if param_info.is_optional:
               dispatcher_emitter.Emit(
                 '    if (!?$OPT_PARAM_NAME) {\n'
                 '      return $FACTORY._create($FACTORY_PARAMS);\n'
                 '    }\n',
                 OPT_PARAM_NAME=param_info.name,
                 FACTORY=factory_name,
                 FACTORY_PARAMS=constructor_info.ParametersAsArgumentList(index))
         else:
           inits = self._members_emitter.Emit(
-              '\n  $(ANNOTATIONS)'
+              '\n  $(METADATA)'
               'factory $CONSTRUCTOR($PARAMS) {\n'
               '    var e = $FACTORY.$CTOR_FACTORY_NAME($FACTORY_PARAMS);\n'
               '$!INITS'
               '    return e;\n'
               '  }\n',
               CONSTRUCTOR=constructor_info._ConstructorFullName(self._DartType),
-              ANNOTATIONS=annotations,
+              METADATA=metadata,
               FACTORY=factory_name,
               CTOR_FACTORY_NAME=factory_constructor_name,
               PARAMS=constructor_info.ParametersDeclaration(self._DartType),
               FACTORY_PARAMS=factory_parameters)
 
           for index, param_info in enumerate(constructor_info.param_infos):
             if param_info.is_optional:
               inits.Emit('    if ($E != null) e.$E = $E;\n', E=param_info.name)
     else:
       def GenerateCall(
@@ skipping 12 matching lines @@
       def IsOptional(signature_index, argument):
         return self.IsConstructorArgumentOptional(argument)
 
       custom_factory_ctr = self._interface.id in _custom_factories
       constructor_full_name = constructor_info._ConstructorFullName(
           self._DartType)
       self._GenerateOverloadDispatcher(
           constructor_info.idl_args,
           False,
           [info.name for info in constructor_info.param_infos],
-          emitter.Format('$(ANNOTATIONS)$FACTORY_KEYWORD $CTOR($PARAMS)',
+          emitter.Format('$(METADATA)$FACTORY_KEYWORD $CTOR($PARAMS)',
             FACTORY_KEYWORD=('factory' if not custom_factory_ctr else
                 'static %s' % constructor_full_name),
             CTOR=(('' if not custom_factory_ctr else '_factory')
                 + constructor_full_name),
-            ANNOTATIONS=annotations,
+            METADATA=metadata,
             PARAMS=constructor_info.ParametersDeclaration(self._DartType)),
           GenerateCall,
           IsOptional)
 
   def _AddFutureifiedOperation(self, info, html_name):
     """Given a API function that uses callbacks, convert it to using Futures.
 
     This conversion assumes the success callback is always provided before the
     error callback (and so far in the DOM API, this is the case)."""
     callback_info = GetCallbackInfo(
         self._database.GetInterface(info.callback_args[0].type_id))
 
     param_list = info.ParametersAsArgumentList()
-    annotations = ''
+    metadata = ''
     if '_RenamingAnnotation' in dir(self):
-      annotations = (self._RenamingAnnotation(info.declared_name, html_name) +
-          self._Annotations(info.type_name, info.declared_name))
+      metadata = (self._RenamingAnnotation(info.declared_name, html_name) +
+          self._Metadata(info.type_name, info.declared_name))
     self._members_emitter.Emit(
         '\n'
-        '  $ANNOTATIONS$MODIFIERS$TYPE$FUTURE_GENERIC $NAME($PARAMS) {\n'
+        '  $METADATA$MODIFIERS$TYPE$FUTURE_GENERIC $NAME($PARAMS) {\n'
         '    var completer = new Completer$(FUTURE_GENERIC)();\n'
         '    $ORIGINAL_FUNCTION($PARAMS_LIST\n'
         '        $NAMED_PARAM($VARIABLE_NAME) { '
         'completer.complete($VARIABLE_NAME); }'
         '$ERROR_CALLBACK);\n'
         '    return completer.future;\n'
         '  }\n',
-        ANNOTATIONS=annotations,
+        METADATA=metadata,
         MODIFIERS='static ' if info.IsStatic() else '',
         TYPE=self.SecureOutputType(info.type_name),
         NAME=html_name[1:],
         PARAMS=info.ParametersDeclaration(self._NarrowInputType
             if '_NarrowInputType' in dir(self) else self._DartType),
         PARAMS_LIST='' if param_list == '' else param_list + ',',
         NAMED_PARAM=('%s : ' % info.callback_args[0].name
             if info.requires_named_arguments and
               info.callback_args[0].is_optional else ''),
         VARIABLE_NAME= '' if len(callback_info.param_infos) == 0 else 'value',
@@ skipping 109 matching lines @@
         walk(interface.parents)
       else:
         walk(interface.parents[1:])
     return result
 
   def _DartType(self, type_name):
     return self._type_registry.DartType(type_name)
 
   def _IsPrivate(self, name):
     return name.startswith('_')