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

tools/dom/scripts/systemhtml.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
 import monitored
@@ skipping 408 matching lines @@
     self._database = options.database
     self._template_loader = options.templates
     self._type_registry = options.type_registry
     self._options = options
     self._library_emitter = library_emitter
     self._event_generator = event_generator
     self._interface = interface
     self._backend = backend
     self._interface_type_info = self._type_registry.TypeInfo(self._interface.id)
     self._library_name = self._renamer.GetLibraryName(self._interface)
+    self._metadata = options.metadata
 
   def Generate(self):
     if IsCustomType(self._interface.id):
       pass
     elif 'Callback' in self._interface.ext_attrs:
       self.GenerateCallback()
     else:
       self.GenerateInterface()
 
   def GenerateCallback(self):
@@ skipping 72 matching lines @@
         implements.append(parent_type_info.interface_name())
 
     secure_base_name = self._backend.SecureBaseName(interface_name)
     if secure_base_name:
       implements.append(secure_base_name)
 
     implements_str = ''
     if implements:
       implements_str = ' implements ' + ', '.join(set(implements))
 
-    annotations = FormatAnnotationsAndComments(
-        GetAnnotationsAndComments(self._library_name,
-                                  self._interface.doc_js_name), '')
+    annotations = self._metadata.GetFormattedMetadata(
+        self._library_name, self._interface.doc_js_name, '')
 
     class_modifiers = ''
     if self._renamer.ShouldSuppressInterface(self._interface):
       class_modifiers = 'abstract '
 
     self._implementation_members_emitter = implementation_emitter.Emit(
         self._backend.ImplementationTemplate(),
         LIBRARYNAME='dart.dom.%s' % self._library_name,
         ANNOTATIONS=annotations,
         CLASS_MODIFIERS=class_modifiers,
@@ skipping 48 matching lines @@
   interface.
   """
 
   def __init__(self, interface, options):
     super(Dart2JSBackend, self).__init__(interface, options)
 
     self._database = options.database
     self._template_loader = options.templates
     self._type_registry = options.type_registry
     self._renamer = options.renamer
+    self._metadata = options.metadata
     self._interface_type_info = self._type_registry.TypeInfo(self._interface.id)
     self._current_secondary_parent = None
     self._library_name = self._renamer.GetLibraryName(self._interface)
 
   def ImplementsMergedMembers(self):
     return True
 
   def GenerateCallback(self, info):
     pass
 
@@ skipping 164 matching lines @@
 
     # If the type has a conversion we need a getter or setter to contain the
     # conversion code.
     if (self._OutputConversion(attribute.type.id, attribute.id) or
         self._InputConversion(attribute.type.id, attribute.id)):
       self._AddAttributeUsingProperties(attribute, html_name, read_only)
       return
 
     output_type = self.SecureOutputType(attribute.type.id)
     input_type = self._NarrowInputType(attribute.type.id)
-    annotations = self._Annotations(attribute.type.id, attribute.id)
+    metadata = self._Metadata(attribute.type.id, attribute.id)
     rename = self._RenamingAnnotation(attribute.id, html_name)
     if not read_only:
       self._members_emitter.Emit(
-          '\n  $RENAME$ANNOTATIONS$TYPE $NAME;'
+          '\n  $RENAME$METADATA$TYPE $NAME;'
           '\n',
           RENAME=rename,
-          ANNOTATIONS=annotations,
+          METADATA=metadata,
           NAME=html_name,
           TYPE=output_type)
     else:
       template = '\n  $RENAME$(ANNOTATIONS)final $TYPE $NAME;\n'
       # Need to use a getter for list.length properties so we can add a
       # setter which throws an exception, satisfying List API.
       if self._interface_type_info.list_item_type() and html_name == 'length':
         template = ('\n  $RENAME$(ANNOTATIONS)$TYPE get $NAME => ' +
             'JS("$TYPE", "#.$NAME", this);\n')
       self._members_emitter.Emit(
           template,
           RENAME=rename,
-          ANNOTATIONS=annotations,
+          ANNOTATIONS=metadata,
           NAME=html_name,
           TYPE=output_type)
 
   def _AddAttributeUsingProperties(self, attribute, html_name, read_only):
     self._AddRenamingGetter(attribute, html_name)
     if not read_only:
       self._AddRenamingSetter(attribute, html_name)
 
   def _AddInterfaceAttribute(self, attribute, html_name):
     self._members_emitter.Emit(
@@ skipping 30 matching lines @@
         '\n  }'
         '\n',
         HTML_NAME=html_name,
         NAME=attr.id,
         TYPE=self._NarrowInputType(attr.type.id))
 
   def _AddConvertingGetter(self, attr, html_name, conversion):
     self._members_emitter.Emit(
         '\n  $RETURN_TYPE get $HTML_NAME => $CONVERT(this._get_$(HTML_NAME));'
         "\n  @JSName('$NAME')"
-        '\n  $(ANNOTATIONS)final $NATIVE_TYPE _get_$HTML_NAME;'
+        '\n  $(METADATA)final $NATIVE_TYPE _get_$HTML_NAME;'
         '\n',
-        ANNOTATIONS=self._Annotations(attr.type.id, html_name),
+        METADATA=self._Metadata(attr.type.id, html_name),
         CONVERT=conversion.function_name,
         HTML_NAME=html_name,
         NAME=attr.id,
         RETURN_TYPE=conversion.output_type,
         NATIVE_TYPE=conversion.input_type)
 
   def _AddConvertingSetter(self, attr, html_name, conversion):
     self._members_emitter.Emit(
         # TODO(sra): Use metadata to provide native name.
         '\n  void set $HTML_NAME($INPUT_TYPE value) {'
@@ skipping 26 matching lines @@
       self._AddFutureifiedOperation(info, html_name)
     elif any(self._OperationRequiresConversions(op) for op in info.overloads):
       # Any conversions needed?
       self._AddOperationWithConversions(info, html_name)
     else:
       self._AddDirectNativeOperation(info, html_name)
 
   def _AddDirectNativeOperation(self, info, html_name):
     self._members_emitter.Emit(
         '\n'
-        '  $RENAME$ANNOTATIONS$MODIFIERS$TYPE $NAME($PARAMS) native;\n',
+        '  $RENAME$METADATA$MODIFIERS$TYPE $NAME($PARAMS) native;\n',
         RENAME=self._RenamingAnnotation(info.declared_name, html_name),
-        ANNOTATIONS=self._Annotations(info.type_name, info.declared_name),
+        METADATA=self._Metadata(info.type_name, info.declared_name),
         MODIFIERS='static ' if info.IsStatic() else '',
         TYPE=self.SecureOutputType(info.type_name),
         NAME=html_name,
         PARAMS=info.ParametersDeclaration(self._NarrowInputType))
 
   def _AddOperationWithConversions(self, info, html_name):
     # Assert all operations have same return type.
     assert len(set([op.type.id for op in info.operations])) == 1
     output_conversion = self._OutputConversion(info.type_name,
                                                info.declared_name)
@@ skipping 59 matching lines @@
       # TODO(sra): If the native method has zero type checks, we can 'inline' is
       # and call it directly with a JS-expression.
       call = '%s(%s)' % (target, argument_list)
 
       if output_conversion:
         call = '%s(%s)' % (output_conversion.function_name, call)
 
       call_emitter.Emit(call)
 
       self._members_emitter.Emit(
-          '  $RENAME$ANNOTATIONS$MODIFIERS$TYPE$TARGET($PARAMS) native;\n',
+          '  $RENAME$METADATA$MODIFIERS$TYPE$TARGET($PARAMS) native;\n',
           RENAME=self._RenamingAnnotation(info.declared_name, target),
-          ANNOTATIONS=self._Annotations(info.type_name, info.declared_name),
+          METADATA=self._Metadata(info.type_name, info.declared_name),
           MODIFIERS='static ' if info.IsStatic() else '',
           TYPE=TypeOrNothing(native_return_type),
           TARGET=target,
           PARAMS=', '.join(target_parameters))
 
     declaration = '%s%s%s %s(%s)' % (
-        self._Annotations(info.type_name, info.declared_name),
+        self._Metadata(info.type_name, info.declared_name),
         'static ' if info.IsStatic() else '',
         return_type,
         html_name,
         info.ParametersDeclaration(InputType))
     self._GenerateDispatcherBody(
         operations,
         parameter_names,
         declaration,
         GenerateCall,
         lambda _, argument: IsOptional(argument),
@@ skipping 27 matching lines @@
 
   def _HasCustomImplementation(self, member_name):
     member_name = '%s.%s' % (self._interface.doc_js_name, member_name)
     return member_name in _js_custom_members
 
   def _RenamingAnnotation(self, idl_name, member_name):
     if member_name != idl_name:
       return  "@JSName('%s')\n  " % idl_name
     return ''
 
-  def _Annotations(self, idl_type, idl_member_name, indent='  '):
-    anns = FindDart2JSAnnotationsAndComments(idl_type, self._library_name,
-                                             self._interface.id,
-                                             idl_member_name)
+  def _Metadata(self, idl_type, idl_member_name, indent='  '):
+    anns = self._metadata.GetDart2JSMetadata(
+        idl_type, self._library_name, self._interface.id, idl_member_name)
 
-    if not AnyConversionAnnotations(idl_type, self._interface.id,
-                                  idl_member_name):
+    if not self._metadata.AnyConversionAnnotations(
+        idl_type, self._interface.id, idl_member_name):
       return_type = self.SecureOutputType(idl_type)
       native_type = self._NarrowToImplementationType(idl_type)
       if native_type != return_type:
         anns = anns + [
           "@Returns('%s')" % native_type,
           "@Creates('%s')" % native_type,
         ]
-    return FormatAnnotationsAndComments(anns, indent);
+    return self._metadata.FormatMetadata(anns, indent);
 
   def CustomJSMembers(self):
     return _js_custom_members
 
   def _NarrowToImplementationType(self, type_name):
     return self._type_registry.TypeInfo(type_name).narrow_dart_type()
 
   def _NarrowInputType(self, type_name):
     return self._NarrowToImplementationType(type_name)
 
@@ skipping 96 matching lines @@
     for library_name in libraries:
       self._libraries[library_name] = DartLibrary(
           library_name, template_loader, library_type, output_dir)
 
   def AddFile(self, basename, library_name, path):
     self._libraries[library_name].AddFile(path)
 
   def Emit(self, emitter, auxiliary_dir):
     for lib in self._libraries.values():
       lib.Emit(emitter, auxiliary_dir)