tools/dom/scripts/generator.py - Issue 14455007: Refactoring DOM annotations and comment generation, adding DOM API triage list

Unified Diff: tools/dom/scripts/generator.py

Issue 14455007: Refactoring DOM annotations and comment generation, adding DOM API triage list (Closed) Base URL: https://dart.googlecode.com/svn/branches/bleeding_edge/dart

Patch Set: Created 7 years, 8 months ago

Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.

Jump to:

View side-by-side diff with in-line comments

Download patch

Index: tools/dom/scripts/generator.py

diff --git a/tools/dom/scripts/generator.py b/tools/dom/scripts/generator.py

index 4ace8f656c19db53a816da25e1c41fb0f741842d..c36ec9c40bd0b2dba0e94ce5b11988bf66d53c56 100644

--- a/tools/dom/scripts/generator.py

+++ b/tools/dom/scripts/generator.py

@@ -14,11 +14,6 @@ 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',

@@ -532,467 +527,6 @@ def FindConversion(idl_type, direction, interface, member):

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

- "|Framebuffer|Renderbuffer|Texture')",

- "|Framebuffer|Renderbuffer|Texture')",

- ],

- 'XMLHttpRequest.response': [

- ],

-}, 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

# ------------------------------------------------------------------------------

« tools/dom/scripts/dartmetadata.py ('K') | « tools/dom/scripts/dartmetadata.py ('k') | tools/dom/scripts/htmldartgenerator.py » ('j') | no next file with comments »