Changes between Version 37 and Version 38 of WebKitIDL

Timestamp:

Feb 17, 2012 2:22:48 AM (12 years ago)

Author:

haraken@chromium.org

Comment:

--

WebKitIDL

@@ -106 +106 @@
 In the following explanations, (i), (m), (a) and (p) means that the IDL attribute can be specified on interfaces, methods, attributes and parameters, respectively. For example, (a,p) means that the IDL attribute can be specified on attributes and parameters.
 
-=== * [TreatNullAs](a,p), [TreatUndefinedAs](a,p) ===
+==  [TreatNullAs](a,p), [TreatUndefinedAs](a,p) ==
 
  * [http://dev.w3.org/2006/webapi/WebIDL/#TreatNullAs The spec of TreatNullAs] (Note: The WebKit IDL explained below behaves differently from the spec)
@@ -137 +137 @@
 [TreatUndefinedAs=NullString] must be used with [TreatNullAs=NullString], i.e. [TreatNullAs=NullString, TreatUndefinedAs=NullString].
 
-=== * [TreatReturnedNullStringAs](m,a) ===
+==  [TreatReturnedNullStringAs](m,a) ==
 
 Summary: It controls the behavior when a WebKit null string is returned.
@@ -156 +156 @@
 Without [TreatReturnedNullStringAs=...], if the returned string is a WebKit null string, the returned value becomes a JavaScript empty string ''. Note that what should be specified depends on the spec of each attribute or method.
 
-=== * [Optional](p) ===
+==  [Optional](p) ==
 
 Summary: It allows method overloading for methods whose argument count are different with each other.
@@ -186 +186 @@
 While in [Optional=DefalutIsUndefined] the "supplemented" JavaScript undefined is converted to a WebKit string "undefined", in [Optional=DefaultIsNullString] the "supplemented" JavaScript undefined is converted to a WebKit null string. Specifically, if JavaScript calls func3(100, 200), then HTMLFoo::func3(int a, int b, String c, String d) is called in WebCore. Here 100 is passed to a, 200 is passed to b, a WebKit string "undefined" is passed to c, and a WebKit null string is passed to d.
 
-=== * [Callback](i,p) FIXME ===
+==  [Callback](i,p) FIXME ==
 
 Summary: ADD SUMMARY
@@ -201 +201 @@
 ADD EXPLANATIONS
 
-=== * [Custom](m,a), [JSCustom](m,a), [V8Custom](m,a), [CustomGetter](a), [JSCustomGetter](a), [V8CustomGetter](a), [CustomSetter](a), [JSCustomSetter](a), [V8CustomSetter](a) ===
+==  [Custom](m,a), [JSCustom](m,a), [V8Custom](m,a), [CustomGetter](a), [JSCustomGetter](a), [V8CustomGetter](a), [CustomSetter](a), [JSCustomSetter](a), [V8CustomSetter](a) ==
 
 Summary: If your bindings require special (i.e. "custom") handling, you can write the bindings code as you like.
@@ -328 +328 @@
 Note: ObjC, GObject and CPP bindings do not support custom bindings.
 
-=== * [CallWith](i,m,a) ===
+==  [CallWith](i,m,a) ==
 
 Summary: It calls a WebCore method with additional information.
@@ -358 +358 @@
 HTMLFoo::func3(ScriptArguments* arguments, ScriptCallStack* callstack, int a, int b) is called.
 
-=== * [CheckAccessToNode](m,a) ===
+==  [CheckAccessToNode](m,a) ==
 
 Summary: It checks if a given Node access is allowed in terms of security.
@@ -372 +372 @@
 This is really important for security.
 
-=== * [StrictTypeChecking](m,a) FIXME ===
+==  [StrictTypeChecking](m,a) FIXME ==
 
 Summary: ADD SUMMARY
@@ -384 +384 @@
 ADD EXPLANATIONS
 
-=== * [ReturnNewObject](m,a) ===
+==  [ReturnNewObject](m,a) ==
 
 Summary: It controls whether WebCore can return a cached wrapper object or not.
@@ -409 +409 @@
 
 
-=== * [ImplementedAs](m) ===
+==  [ImplementedAs](m) ==
 
 Summary: It specifies a method name in WebCore implementation, if the IDL method name and the WebCore method name are different.
@@ -423 +423 @@
 You should avoid using [ImplementedAs] as much as possible though.
 
-=== * [Reflect](a) FIXME ===
+==  [Reflect](a) FIXME ==
 
 Summary: ADD SUMMARY
@@ -434 +434 @@
 ADD EXPLANATIONS
 
-=== * [Replaceable](a) ===
+==  [Replaceable](a) ==
 
  * [http://dev.w3.org/2006/webapi/WebIDL/#Replaceable The spec of replaceable]
@@ -471 +471 @@
 
 
-=== * [Deletable](a), [NotEnumerable](a), [V8ReadOnly](a) ===
+==  [Deletable](a), [NotEnumerable](a), [V8ReadOnly](a) ==
 
  * [http://www.ecma-international.org/publications/files/ECMA-ST/Ecma-262.pdf The spec of Writable, Enumerable and Configurable (8.6.1)]
@@ -488 +488 @@
 [Deletable] indicates that the attribute is deletable. [NotEnumerable] indicates that the attribute is not enumerable. [V8ReadOnly] indicates that the attribute is readonly in V8 even if the attribute is not prefixed by "readonly".
 
-=== * [CachedAttribute](a) ===
+==  [CachedAttribute](a) ==
 
 Summary: For performance optimization, it indicates to cache a wrapped object in a DOM object.
@@ -539 +539 @@
 but also it increases the overhead of "cache-miss"ed getters and setters (Setters always need to invalidate the caches).
 
-=== * [V8Unforgeable](m,a), [V8OnProto](m,a) ===
+==  [V8Unforgeable](m,a), [V8OnProto](m,a) ==
 
  * [http://dev.w3.org/2006/webapi/WebIDL/#Unforgeable The spec of Unforgeable]
@@ -563 +563 @@
 You should not use them unless you have a strong reason to use them.
 
-=== * [URL](a) ===
+==  [URL](a) ==
 
 Summary: It indicates that a given DOMString is a URL.
@@ -576 +576 @@
 If you forgot to specify [URL], then the attribute getter might cause a bug.
 
-=== * [JSWindowEventListener](a) FIXME ===
+==  [JSWindowEventListener](a) FIXME ==
 
 Summary: ADD SUMMARY
@@ -587 +587 @@
 ADD EXPLANATIONS
 
-== IDL attributes around interfaces ==
-
-=== * [Supplemental](i) ===
+==  [Supplemental](i) ==
 
  * [http://dev.w3.org/2006/webapi/WebIDL/#dfn-supplemental-interface The spec of Supplemental]
@@ -633 +631 @@
 If you want to add APIs whose implementations are likely to be independent from WebCore, it is strongly recommended to put the APIs and .h/.cpp files into WebCore/Modules/XXX/ using [Supplemental].
 
-=== * [Constructor](i), [CallWith](i,m,a), [ConstructorRaisesException](i) ===
+==  [Constructor](i), [CallWith](i,m,a), [ConstructorRaisesException](i) ==
 
  * [http://dev.w3.org/2006/webapi/WebIDL/#Constructor The spec of Constructor]
@@ -696 +694 @@
 Whether you should allow an interface to have constructor depends on the spec of the interface.
 
-=== * [ConstructorTemplate](i), [InitializedByEventConstructor](a) ===
+==  [ConstructorTemplate](i), [InitializedByEventConstructor](a) ==
 
 Summary: They are used for Event constructors.
@@ -737 +735 @@
 In other words, in case of Event, you should specify [InitializedByEventConstructor] on bubbles and cancelable.
 
-=== * [NamedConstructor](i) ===
+==  [NamedConstructor](i) ==
 
  * [http://dev.w3.org/2006/webapi/WebIDL/#NamedConstructor The spec of NamedConstructor]
@@ -756 +754 @@
 Whether you should allow an interface to have a named constructor depends on the spec of the interface.
 
-=== * [CustomConstructor](i), [JSCustomConstructor](i), [V8CustomConstructor](i), [ConstructorParameters](i) ===
+==  [CustomConstructor](i), [JSCustomConstructor](i), [V8CustomConstructor](i), [ConstructorParameters](i) ==
 
 Summary: They allow us to write custom bindings for constructors.
@@ -825 +823 @@
 You do not need to specify [ConstructorParameters] if the interface does not have any of [JSCustomConstructor], [V8CustomConstructor] or [CustomConstructor].
 
-=== * [Conditional](i,m,a) ===
+==  [Conditional](i,m,a) ==
 
 Summary: It inserts "#if ENABLE(SOME_FLAG) ... #endif" into the generated code.
@@ -849 +847 @@
 If [Conditional] is specified on an interface, it means that [Conditional] is specified on all attributes and methods on the interface.
 
-=== * [V8EnabledAtRuntime](i,m,a) ===
+==  [V8EnabledAtRuntime](i,m,a) ==
 
 Summary: In Chromium/V8, we can enable/disable a flag at runtime.
@@ -887 +885 @@
 and WebKit/chromium/src/WebRuntimeFeatures.cpp for more details.
 
-=== * [CustomToJSObject](i), [JSCustomToJSObject](i), [V8CustomToJSObject](i) ===
+==  [CustomToJSObject](i), [JSCustomToJSObject](i), [V8CustomToJSObject](i) ==
 
 Summary: They allow us to write custom toJS() or toV8().
@@ -919 +917 @@
 }}}
 
-=== * [CheckAccessToFrame](i), [DoNotCheckAccessToFrame](m,a), [DoNotCheckAccessToFrameOnGetter](a), [DoNotCheckAccessToFrameOnSetter](a) ===
+==  [CheckAccessToFrame](i), [DoNotCheckAccessToFrame](m,a), [DoNotCheckAccessToFrameOnGetter](a), [DoNotCheckAccessToFrameOnSetter](a) ==
 
 Summary: It checks if a given Frame access is allowed or not, in terms of security.
@@ -956 +954 @@
  * [DoNotCheckAccessToFrame] on an attribute is equivalent to [DoNotCheckAccessToFrameOnGetter, DoNotCheckAccessToFrameOnSetter].
 
-=== * [IndexedGetter](i) ===
+==  [IndexedGetter](i) ==
 
  * [http://dev.w3.org/2006/webapi/WebIDL/#idl-indexed-properties The spec of indexed properties] (Note: The WebKit IDL explained below behaves differently from the spec)
@@ -973 +971 @@
 The bindings code is generated automatically so that XXX[i] behaves equivalent to XXX.item(i).
 
-=== * [CustomIndexedSetter](i) ===
+==  [CustomIndexedSetter](i) ==
 
  * [http://dev.w3.org/2006/webapi/WebIDL/#idl-indexed-properties The spec of indexed properties] (Note: The WebKit IDL explained below behaves differently from the spec)
@@ -1005 +1003 @@
 }}}
 
-=== * [NamedGetter](i) ===
+==  [NamedGetter](i) ==
 
  * [http://dev.w3.org/2006/webapi/WebIDL/#idl-named-properties The spec of named properties] (Note: The WebKit IDL explained below behaves differently from the spec)
@@ -1022 +1020 @@
 The bindings code is generated automatically so that XXX.foooooooo behaves equivalent to XXX.namedItem(i).
 
-=== [CustomNamedGetter](i), [CustomNamedSetter](i) ===
+== [CustomNamedGetter](i), [CustomNamedSetter](i) ==
 
  * [http://dev.w3.org/2006/webapi/WebIDL/#idl-named-properties The spec of named properties] (Note: The WebKit IDL explained below behaves differently from the spec)
@@ -1075 +1073 @@
 }}}
 
-=== * [EventTarget](i) FIXME ===
+==  [EventTarget](i) FIXME ==
 
 Summary: ADD SUMMARY
@@ -1089 +1087 @@
 ADD EXPLANATIONS
 
-=== * [DoNotCheckConstants](i) ===
+==  [DoNotCheckConstants](i) ==
 
 Summary: [DoNotCheckConstants] stops inserting compile-time assertions for constants of a given interface.
@@ -1112 +1110 @@
 you can specify [DoNotCheckConstants] on the interface to skip the compile-time assertions.
 
-=== * [ActiveDOMObject](i) ===
+==  [ActiveDOMObject](i) ==
 
 Summary: [ActiveDOMObject] indicates that a DOM object should be kept alive when the DOM object has pending activities.
@@ -1130 +1128 @@
 then the interface Y should also have [ActiveDOMObject].
 
-=== * [V8DependentLifeTime](i) FIXME ===
+==  [V8DependentLifeTime](i) FIXME ==
 
 Summary: ADD SUMMARY
@@ -1144 +1142 @@
 ADD EXPLANATIONS
 
-=== * [CustomEnumerateProperty](i), [CustomDeleteProperty](i) ===
+==  [CustomEnumerateProperty](i), [CustomDeleteProperty](i) ==
 
 Summary: [CustomEnumerateProperty] allows us to write custom bindings for the case where properties of a given interface are enumerated.
@@ -1195 +1193 @@
 }}}
 
-=== * [IsWorkerContext](i) ===
+==  [IsWorkerContext](i) ==
 
 Summary: It indicates that the interface is a WorkerContext-related interface.
@@ -1208 +1206 @@
 }}}
 
-=== * [CustomCall](i) ===
+==  [CustomCall](i) ==
 
 Summary: [CustomCall] allows us to write custom bindings for call(...) of a given interface.
@@ -1237 +1235 @@
 }}}
 
-=== * [JSCustomToNativeObject](i), [JSCustomFinalize](i), [JSCustomIsReachable](i), [JSCustomMarkFunction](i), [JSCustomNamedGetterOnPrototype](i), [JSCustomPushEventHandlerScope](i), [JSCustomDefineOwnProperty](i), [JSCustomDefineOwnPropertyOnPrototype](i), [JSCustomGetOwnPropertySlotAndDescriptor](i) ===
+==  [JSCustomToNativeObject](i), [JSCustomFinalize](i), [JSCustomIsReachable](i), [JSCustomMarkFunction](i), [JSCustomNamedGetterOnPrototype](i), [JSCustomPushEventHandlerScope](i), [JSCustomDefineOwnProperty](i), [JSCustomDefineOwnPropertyOnPrototype](i), [JSCustomGetOwnPropertySlotAndDescriptor](i) ==
 
 Summary: They allow us to write custom code for the JavaScriptCore code which would be generated automatically by default.
@@ -1329 +1327 @@
 }}}
 
-=== * [JSGenerateToJSObject](i), [JSGenerateIsReachable](i), [JSGenerateToNativeObject](i) ===
+==  [JSGenerateToJSObject](i), [JSGenerateIsReachable](i), [JSGenerateToNativeObject](i) ==
 
 Summary: They force JavaScriptCore bindings to generate JavaScriptCore specific methods even if a given interface has a parent interface.
@@ -1347 +1345 @@
 [JSGenerateToJSObject], [JSGenerateIsReachable] or [JSGenerateToNativeObject], respectively.
 
-=== * [JSCustomHeader](i) ===
+==  [JSCustomHeader](i) ==
 
 Summary: It allows us to write a custom header for a given interface.
@@ -1364 +1362 @@
 
 
-=== * [JSLegacyParent](i) ===
+==  [JSLegacyParent](i) ==
 
 Summary: It explicitly controls the parent interface of a given interface.
@@ -1378 +1376 @@
 Even if a given interface does not have a parent interface, you can specify a parent interface using [JSLegacyParent].
 
-=== * [JSInlineGetOwnPropertySlot](i) ===
+==  [JSInlineGetOwnPropertySlot](i) ==
 
 Summary: It makes getOwnPropertySlot(...) and getOwnPropertyDescriptor(...) an inline method for performance.
@@ -1390 +1388 @@
 }}}
 
-=== * [JSNoStaticTables](i) FIXME ===
+==  [JSNoStaticTables](i) FIXME ==
 
 Summary: ADD SUMMARY
@@ -1404 +1402 @@
 ADD EXPLANATIONS
 
-== IDL attributes used by ObjC, GObject and CPP bindings only ==
-
-=== * [ObjCProtocol](i), [ObjCPolymorphic](i), [ObjCLegacyUnnamedParameters](m), [ObjCUseDefaultView](m), [ObjCImplementedAsUnsignedLongLong](a) ===
+==  [ObjCProtocol](i), [ObjCPolymorphic](i), [ObjCLegacyUnnamedParameters](m), [ObjCUseDefaultView](m), [ObjCImplementedAsUnsignedLongLong](a) ==
 
 Used by ObjC bindings only.
 
-=== * [CPPPureInterface](i) ===
+==  [CPPPureInterface](i) ==
 
 Used by CPP bindings only.
 
-=== * [CustomReturn](p) ===
+==  [CustomReturn](p) ==
 
 Used by ObjC, GObject and CPP bindings only.
 
-== IDL attributes which might be deprecated ==
-
-=== * [OmitConstructor], [Immutable], [MasqueradesAsUndefined] ===
+==  [OmitConstructor], [Immutable], [MasqueradesAsUndefined] ==
 
 Might be deprecated. Discussion is on-going.
 
-=== * [CustomGetOwnPropertySlot], [ReplaceableConstructor], [ExtendsDOMGlobalObject], [IsIndex], [V8DoNotCheckSignature], [NumericIndexedGetter] ===
+==  [CustomGetOwnPropertySlot], [ReplaceableConstructor], [ExtendsDOMGlobalObject], [IsIndex], [V8DoNotCheckSignature], [NumericIndexedGetter] ==
 
 Will be deprecated. Discussion is on-going.