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

tools/dom/scripts/generator.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 systems to generate
 Dart APIs from the IDL database."""
 
 import copy
 import json
 import monitored
 import os
 import re
 from htmlrenamer import html_interface_renames, renamed_html_members, \
      typed_array_renames
 
-# Set up json file for retrieving comments.
-_current_dir = os.path.dirname(__file__)
-_json_path = os.path.join(_current_dir, '..', 'docs', 'docs.json')
-_dom_json = json.load(open(_json_path))
-
 _pure_interfaces = monitored.Set('generator._pure_interfaces', [
     # TODO(sra): DOMStringMap should be a class implementing Map<String,String>.
     'DOMStringMap',
     'ElementTimeControl',
     'ElementTraversal',
     'EventListener',
     'MediaQueryListListener',
     'MutationCallback',
     'SVGExternalResourcesRequired',
     'SVGFilterPrimitiveStandardAttributes',
@@ skipping 493 matching lines @@
 }, dart2jsOnly=True)
 
 def FindConversion(idl_type, direction, interface, member):
   table = dart2js_conversions
   return (table.get('%s %s %s.%s' % (idl_type, direction, interface, member)) or
           table.get('* %s %s.%s' % (direction, interface, member)) or
           table.get('%s %s %s.*' % (idl_type, direction, interface)) or
           table.get('%s %s' % (idl_type, direction)))
   return None
 
-# ------------------------------------------------------------------------------
-
-# Annotations to be placed on native members.  The table is indexed by the IDL
-# interface and member name, and by IDL return or field type name.  Both are
-# used to assemble the annotations:
-#
-#   INTERFACE.MEMBER: annotations for member.
-#   +TYPE:            add annotations only if there are member annotations.
-#   -TYPE:            add annotations only if there are no member annotations.
-#   TYPE:             add regardless of member annotations.
-
-dart2js_annotations = monitored.Dict('generator.dart2js_annotations', {
-
-    'ArrayBufferView': [
-      "@Creates('TypedData')",
-      "@Returns('TypedData|Null')",
-    ],
-
-    'CanvasRenderingContext2D.createImageData': [
-      "@Creates('ImageData|=Object')",
-    ],
-
-    'CanvasRenderingContext2D.getImageData': [
-      "@Creates('ImageData|=Object')",
-    ],
-
-    'CanvasRenderingContext2D.webkitGetImageDataHD': [
-      "@Creates('ImageData|=Object')",
-    ],
-
-    'CanvasRenderingContext2D.fillStyle': [
-      "@Creates('String|CanvasGradient|CanvasPattern')",
-      "@Returns('String|CanvasGradient|CanvasPattern')",
-    ],
-
-    'CanvasRenderingContext2D.strokeStyle': [
-      "@Creates('String|CanvasGradient|CanvasPattern')",
-      "@Returns('String|CanvasGradient|CanvasPattern')",
-    ],
-
-    # Methods returning Window can return a local window, or a cross-frame
-    # window (=Object) that needs wrapping.
-    'DOMWindow': [
-      "@Creates('Window|=Object')",
-      "@Returns('Window|=Object')",
-    ],
-
-    'DOMWindow.openDatabase': [
-      "@Creates('SqlDatabase')",
-    ],
-
-    # To be in callback with the browser-created Event, we had to have called
-    # addEventListener on the target, so we avoid
-    'Event.currentTarget': [
-      "@Creates('Null')",
-      "@Returns('EventTarget|=Object')",
-    ],
-
-    # Only nodes in the DOM bubble and have target !== currentTarget.
-    'Event.target': [
-      "@Creates('Node')",
-      "@Returns('EventTarget|=Object')",
-    ],
-
-    'MouseEvent.relatedTarget': [
-      "@Creates('Node')",
-      "@Returns('EventTarget|=Object')",
-    ],
-
-    # Touch targets are Elements in a Document, or the Document.
-    'Touch.target': [
-      "@Creates('Element|Document')",
-      "@Returns('Element|Document')",
-    ],
-
-    'FileReader.result': ["@Creates('String|ByteBuffer|Null')"],
-
-    # Rather than have the result of an IDBRequest as a union over all possible
-    # results, we mark the result as instantiating any classes, and mark
-    # each operation with the classes that it could cause to be asynchronously
-    # instantiated.
-    'IDBRequest.result': ["@Creates('Null')"],
-
-    # The source is usually a participant in the operation that generated the
-    # IDBRequest.
-    'IDBRequest.source':  ["@Creates('Null')"],
-
-    'IDBFactory.open': ["@Creates('Database')"],
-    'IDBFactory.webkitGetDatabaseNames': ["@Creates('DomStringList')"],
-
-    'IDBObjectStore.put': ["@_annotation_Creates_IDBKey"],
-    'IDBObjectStore.add': ["@_annotation_Creates_IDBKey"],
-    'IDBObjectStore.get': ["@annotation_Creates_SerializedScriptValue"],
-    'IDBObjectStore.openCursor': ["@Creates('Cursor')"],
-
-    'IDBIndex.get': ["@annotation_Creates_SerializedScriptValue"],
-    'IDBIndex.getKey': [
-      "@annotation_Creates_SerializedScriptValue",
-      # The source is the object store behind the index.
-      "@Creates('ObjectStore')",
-    ],
-    'IDBIndex.openCursor': ["@Creates('Cursor')"],
-    'IDBIndex.openKeyCursor': ["@Creates('Cursor')"],
-
-    'IDBCursorWithValue.value': [
-      '@annotation_Creates_SerializedScriptValue',
-      '@annotation_Returns_SerializedScriptValue',
-    ],
-
-    'IDBCursor.key': [
-      "@_annotation_Creates_IDBKey",
-      "@_annotation_Returns_IDBKey",
-    ],
-
-    '+IDBRequest': [
-      "@Returns('Request')",
-      "@Creates('Request')",
-    ],
-
-    '+IDBOpenDBRequest': [
-      "@Returns('Request')",
-      "@Creates('Request')",
-    ],
-
-    'MessageEvent.ports': ["@Creates('=List')"],
-
-    'MessageEvent.data': [
-      "@annotation_Creates_SerializedScriptValue",
-      "@annotation_Returns_SerializedScriptValue",
-    ],
-    'PopStateEvent.state': [
-      "@annotation_Creates_SerializedScriptValue",
-      "@annotation_Returns_SerializedScriptValue",
-    ],
-    'SerializedScriptValue': [
-      "@annotation_Creates_SerializedScriptValue",
-      "@annotation_Returns_SerializedScriptValue",
-    ],
-
-    'SQLResultSetRowList.item': ["@Creates('=Object')"],
-
-    'WebGLRenderingContext.getParameter': [
-      # Taken from http://www.khronos.org/registry/webgl/specs/latest/
-      # Section 5.14.3 Setting and getting state
-      "@Creates('Null|num|String|bool|=List|Float32List|Int32List|Uint32List"
-                "|Framebuffer|Renderbuffer|Texture')",
-      "@Returns('Null|num|String|bool|=List|Float32List|Int32List|Uint32List"
-                "|Framebuffer|Renderbuffer|Texture')",
-    ],
-
-    'XMLHttpRequest.response': [
-      "@Creates('ByteBuffer|Blob|Document|=Object|=List|String|num')",
-    ],
-}, dart2jsOnly=True)
-
-_indexed_db_annotations = [
-  "@SupportedBrowser(SupportedBrowser.CHROME)",
-  "@SupportedBrowser(SupportedBrowser.FIREFOX, '15')",
-  "@SupportedBrowser(SupportedBrowser.IE, '10')",
-  "@Experimental",
-]
-
-_file_system_annotations = [
-  "@SupportedBrowser(SupportedBrowser.CHROME)",
-  "@Experimental",
-]
-
-_all_but_ie9_annotations = [
-  "@SupportedBrowser(SupportedBrowser.CHROME)",
-  "@SupportedBrowser(SupportedBrowser.FIREFOX)",
-  "@SupportedBrowser(SupportedBrowser.IE, '10')",
-  "@SupportedBrowser(SupportedBrowser.SAFARI)",
-]
-
-_history_annotations = _all_but_ie9_annotations
-
-_no_ie_annotations = [
-  "@SupportedBrowser(SupportedBrowser.CHROME)",
-  "@SupportedBrowser(SupportedBrowser.FIREFOX)",
-  "@SupportedBrowser(SupportedBrowser.SAFARI)",
-]
-
-_performance_annotations = [
-  "@SupportedBrowser(SupportedBrowser.CHROME)",
-  "@SupportedBrowser(SupportedBrowser.FIREFOX)",
-  "@SupportedBrowser(SupportedBrowser.IE)",
-]
-
-_rtc_annotations = [ # Note: Firefox nightly builds also support this.
-  "@SupportedBrowser(SupportedBrowser.CHROME)",
-  "@Experimental",
-]
-
-_shadow_dom_annotations = [
-  "@SupportedBrowser(SupportedBrowser.CHROME, '26')",
-  "@Experimental",
-]
-
-_speech_recognition_annotations = [
-  "@SupportedBrowser(SupportedBrowser.CHROME, '25')",
-  "@Experimental",
-]
-
-_svg_annotations = _all_but_ie9_annotations;
-
-_web_sql_annotations = [
-  "@SupportedBrowser(SupportedBrowser.CHROME)",
-  "@SupportedBrowser(SupportedBrowser.SAFARI)",
-  "@Experimental",
-]
-
-_webgl_annotations = [
-  "@SupportedBrowser(SupportedBrowser.CHROME)",
-  "@SupportedBrowser(SupportedBrowser.FIREFOX)",
-  "@Experimental",
-]
-
-_webkit_experimental_annotations = [
-  "@SupportedBrowser(SupportedBrowser.CHROME)",
-  "@SupportedBrowser(SupportedBrowser.SAFARI)",
-  "@Experimental",
-]
-
-# Annotations to be placed on generated members.
-# The table is indexed as:
-#   INTERFACE:     annotations to be added to the interface declaration
-#   INTERFACE.MEMBER: annotation to be added to the member declaration
-dart_annotations = monitored.Dict('generator.dart_annotations', {
-  'CSSHostRule': _shadow_dom_annotations,
-  'Crypto': _webkit_experimental_annotations,
-  'Database': _web_sql_annotations,
-  'DatabaseSync': _web_sql_annotations,
-  'DOMApplicationCache': [
-    "@SupportedBrowser(SupportedBrowser.CHROME)",
-    "@SupportedBrowser(SupportedBrowser.FIREFOX)",
-    "@SupportedBrowser(SupportedBrowser.IE, '10')",
-    "@SupportedBrowser(SupportedBrowser.OPERA)",
-    "@SupportedBrowser(SupportedBrowser.SAFARI)",
-  ],
-  'DOMFileSystem': _file_system_annotations,
-  'DOMFileSystemSync': _file_system_annotations,
-  'DOMWindow.webkitConvertPointFromNodeToPage': _webkit_experimental_annotations,
-  'DOMWindow.webkitConvertPointFromPageToNode': _webkit_experimental_annotations,
-  'DOMWindow.indexedDB': _indexed_db_annotations,
-  'DOMWindow.openDatabase': _web_sql_annotations,
-  'DOMWindow.performance': _performance_annotations,
-  'DOMWindow.webkitNotifications': _webkit_experimental_annotations,
-  'DOMWindow.webkitRequestFileSystem': _file_system_annotations,
-  'DOMWindow.webkitResolveLocalFileSystemURL': _file_system_annotations,
-  'Element.onwebkitTransitionEnd': _all_but_ie9_annotations,
-  # Placeholder to add experimental flag, implementation for this is
-  # pending in a separate CL.
-  'Element.webkitMatchesSelector': ['@Experimental()'],
-  'Element.webkitCreateShadowRoot': [
-    "@SupportedBrowser(SupportedBrowser.CHROME, '25')",
-    "@Experimental",
-  ],
-  'Event.clipboardData': _webkit_experimental_annotations,
-  'FormData': _all_but_ie9_annotations,
-  'HashChangeEvent': [
-    "@SupportedBrowser(SupportedBrowser.CHROME)",
-    "@SupportedBrowser(SupportedBrowser.FIREFOX)",
-    "@SupportedBrowser(SupportedBrowser.SAFARI)",
-  ],
-  'History.pushState': _history_annotations,
-  'History.replaceState': _history_annotations,
-  'HTMLContentElement': _shadow_dom_annotations,
-  'HTMLDataListElement': _all_but_ie9_annotations,
-  'HTMLDetailsElement': _webkit_experimental_annotations,
-  'HTMLEmbedElement': [
-    "@SupportedBrowser(SupportedBrowser.CHROME)",
-    "@SupportedBrowser(SupportedBrowser.IE)",
-    "@SupportedBrowser(SupportedBrowser.SAFARI)",
-  ],
-  'HTMLKeygenElement': _webkit_experimental_annotations,
-  'HTMLMeterElement': _no_ie_annotations,
-  'HTMLObjectElement': [
-    "@SupportedBrowser(SupportedBrowser.CHROME)",
-    "@SupportedBrowser(SupportedBrowser.IE)",
-    "@SupportedBrowser(SupportedBrowser.SAFARI)",
-  ],
-  'HTMLOutputElement': _no_ie_annotations,
-  'HTMLProgressElement': _all_but_ie9_annotations,
-  'HTMLShadowElement': _shadow_dom_annotations,
-  'HTMLTrackElement': [
-    "@SupportedBrowser(SupportedBrowser.CHROME)",
-    "@SupportedBrowser(SupportedBrowser.IE, '10')",
-    "@SupportedBrowser(SupportedBrowser.SAFARI)",
-  ],
-  'IDBFactory': _indexed_db_annotations,
-  'IDBDatabase': _indexed_db_annotations,
-  'LocalMediaStream': _rtc_annotations,
-  'MediaStream': _rtc_annotations,
-  'MediaStreamEvent': _rtc_annotations,
-  'MediaStreamTrack': _rtc_annotations,
-  'MediaStreamTrackEvent': _rtc_annotations,
-  'MutationObserver': [
-    "@SupportedBrowser(SupportedBrowser.CHROME)",
-    "@SupportedBrowser(SupportedBrowser.FIREFOX)",
-    "@SupportedBrowser(SupportedBrowser.SAFARI)",
-    "@Experimental",
-  ],
-  'NotificationCenter': _webkit_experimental_annotations,
-  'Performance': _performance_annotations,
-  'PopStateEvent': _history_annotations,
-  'RTCIceCandidate': _rtc_annotations,
-  'RTCPeerConnection': _rtc_annotations,
-  'RTCSessionDescription': _rtc_annotations,
-  'ShadowRoot': _shadow_dom_annotations,
-  'SpeechRecognition': _speech_recognition_annotations,
-  'SpeechRecognitionAlternative': _speech_recognition_annotations,
-  'SpeechRecognitionError': _speech_recognition_annotations,
-  'SpeechRecognitionEvent': _speech_recognition_annotations,
-  'SpeechRecognitionResult': _speech_recognition_annotations,
-  'SVGAltGlyphElement': _no_ie_annotations,
-  'SVGAnimateElement': _no_ie_annotations,
-  'SVGAnimateMotionElement': _no_ie_annotations,
-  'SVGAnimateTransformElement': _no_ie_annotations,
-  'SVGFEBlendElement': _svg_annotations,
-  'SVGFEColorMatrixElement': _svg_annotations,
-  'SVGFEComponentTransferElement': _svg_annotations,
-  'SVGFEConvolveMatrixElement': _svg_annotations,
-  'SVGFEDiffuseLightingElement': _svg_annotations,
-  'SVGFEDisplacementMapElement': _svg_annotations,
-  'SVGFEDistantLightElement': _svg_annotations,
-  'SVGFEFloodElement': _svg_annotations,
-  'SVGFEFuncAElement': _svg_annotations,
-  'SVGFEFuncBElement': _svg_annotations,
-  'SVGFEFuncGElement': _svg_annotations,
-  'SVGFEFuncRElement': _svg_annotations,
-  'SVGFEGaussianBlurElement': _svg_annotations,
-  'SVGFEImageElement': _svg_annotations,
-  'SVGFEMergeElement': _svg_annotations,
-  'SVGFEMergeNodeElement': _svg_annotations,
-  'SVGFEMorphologyElement': _svg_annotations,
-  'SVGFEOffsetElement': _svg_annotations,
-  'SVGFEPointLightElement': _svg_annotations,
-  'SVGFESpecularLightingElement': _svg_annotations,
-  'SVGFESpotLightElement': _svg_annotations,
-  'SVGFETileElement': _svg_annotations,
-  'SVGFETurbulenceElement': _svg_annotations,
-  'SVGFilterElement': _svg_annotations,
-  'SVGForeignObjectElement': _no_ie_annotations,
-  'SVGSetElement': _no_ie_annotations,
-  'SQLTransaction': _web_sql_annotations,
-  'SQLTransactionSync': _web_sql_annotations,
-  'WebGLRenderingContext': _webgl_annotations,
-  'WebKitCSSMatrix': _webkit_experimental_annotations,
-  'WebKitPoint': _webkit_experimental_annotations,
-  'WebSocket': _all_but_ie9_annotations,
-  'Worker': _all_but_ie9_annotations,
-  'XMLHttpRequest.onloadend': _all_but_ie9_annotations,
-  'XMLHttpRequest.onprogress': _all_but_ie9_annotations,
-  'XMLHttpRequest.response': _all_but_ie9_annotations,
-  'XMLHttpRequestProgressEvent': _webkit_experimental_annotations,
-  'XSLTProcessor': [
-    "@SupportedBrowser(SupportedBrowser.CHROME)",
-    "@SupportedBrowser(SupportedBrowser.FIREFOX)",
-    "@SupportedBrowser(SupportedBrowser.SAFARI)",
-  ],
-})
-
-def GetComments(library_name, interface_name, member_name=None):
-  """ Finds 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 _dom_json and interface_name in _dom_json[library_name]:
-    if (member_name and 'members' in _dom_json[library_name][interface_name] and
-        (member_name in _dom_json[library_name][interface_name]['members'])):
-      comments = _dom_json[library_name][interface_name]['members'][member_name]
-    elif (not member_name and 'comment' in
-          _dom_json[library_name][interface_name]):
-      comments = _dom_json[library_name][interface_name]['comment']
-
-  if (len(comments)):
-    comments = ['\n'.join(comments)]
-
-  return comments
-
-def GetAnnotationsAndComments(library_name, interface_name, member_name=None):
-  annotations = GetComments(library_name, interface_name, member_name)
-  annotations = annotations + (FindCommonAnnotations(library_name, interface_name,
-                                                     member_name))
-
-  return annotations
-
-def FindCommonAnnotations(library_name, interface_name, member_name=None):
-  """ Finds annotations common between dart2js and dartium.
-  """
-  if member_name:
-    key = '%s.%s' % (interface_name, member_name)
-  else:
-    key = interface_name
-
-  annotations = ["@DomName('" + key + "')"]
-
-  # Only add this for members, so we don't add DocsEditable to templated classes
-  # (they get it from the default class template)
-  if member_name:
-    annotations.append('@DocsEditable');
-
-  if (dart_annotations.get(key) != None):
-    annotations.extend(dart_annotations.get(key))
-
-  if (member_name and member_name.startswith('webkit') and
-      key not in renamed_html_members):
-    annotations.extend(_webkit_experimental_annotations)
-
-  return annotations
-
-def FindDart2JSAnnotationsAndComments(idl_type, library_name, interface_name,
-                                      member_name,):
-  """ Finds all annotations for Dart2JS members- including annotations for
-  both dart2js and dartium.
-  """
-  annotations = GetAnnotationsAndComments(library_name, interface_name, member_name)
-
-  ann2 = _FindDart2JSSpecificAnnotations(idl_type, interface_name, member_name)
-  if ann2:
-    if annotations:
-      annotations.extend(ann2)
-    else:
-      annotations = ann2
-  return annotations
-
-def AnyConversionAnnotations(idl_type, interface_name, member_name):
-  if (dart_annotations.get('%s.%s' % (interface_name, member_name)) or
-      _FindDart2JSSpecificAnnotations(idl_type, interface_name, member_name)):
-    return True
-  else:
-    return False
-
-def FormatAnnotationsAndComments(annotations, indentation):
-  if annotations:
-
-    newline = '\n%s' % indentation
-    result = newline.join(annotations) + newline
-    return result
-  return ''
-
-def _FindDart2JSSpecificAnnotations(idl_type, interface_name, member_name):
-  """ Finds dart2js-specific annotations. This does not include ones shared with
-  dartium.
-  """
-  ann1 = dart2js_annotations.get("%s.%s" % (interface_name, member_name))
-  if ann1:
-    ann2 = dart2js_annotations.get('+' + idl_type)
-    if ann2:
-      return ann2 + ann1
-    ann2 = dart2js_annotations.get(idl_type)
-    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
 
 # ------------------------------------------------------------------------------
 
 class IDLTypeInfo(object):
   def __init__(self, idl_type, data):
     self._idl_type = idl_type
     self._data = data
 
   def idl_type(self):
     return self._idl_type
@@ skipping 566 matching lines @@
           type_name, type_data, dart_interface_name, self)
 
     if type_data.clazz == 'BasicTypedList':
       dart_interface_name = self._renamer.RenameInterface(
           self._database.GetInterface(type_name))
       return BasicTypedListIDLTypeInfo(
           type_name, type_data, dart_interface_name, self)
 
     class_name = '%sIDLTypeInfo' % type_data.clazz
     return globals()[class_name](type_name, type_data)