Changes between Version 31 and Version 32 of WebKitIDL

Timestamp:

Feb 15, 2012 9:39:22 PM (12 years ago)

Author:

haraken@chromium.org

Comment:

--

WebKitIDL

@@ -131 +131 @@
     attribute [CustomGetter, JSCustomSetter] DOMString str;
 }}}
+
+We should minimize the number of custom bindings as less as possible.
+Before using [Custom], you should doubly consider if you really need custom bindings.
+You are recommended to modify code generators to avoid using [Custom].
 
 Before explaining the details, let us clarify the relationship of these IDL attributes.
@@ -243 +247 @@
 Refer to WebCore/bindings/v8/custom/V8XXXCustom.cpp for more details.
 
-We should minimize the number of custom bindings as less as possible. Before using [Custom], you should doubly consider if you really need custom bindings.
-
 Note: ObjC, GObject and CPP bindings do not support custom bindings.
 
@@ -564 +566 @@
         CallWith=ScriptExecutionContext|ScriptState
     ] XXX {
-        ...;
     }
 }}}
@@ -658 +659 @@
 === * [NamedConstructor](i) ===
 
-=== * [CustomConstructor](i), [JSCustomConstructor](i), [V8CustomConstructor](i) ===
+ * [http://dev.w3.org/2006/webapi/WebIDL/#NamedConstructor The spec of NamedConstructor]
+
+Summary: If the interface name XXX and "new YYY()" name are different (i.e. XXX != YYY), you can use [NamedConstructor].
+
+Usage: The possible usage of [NamedConstructor] is [NamedConstructor=YYY].
+[NamedConstructor] can be specified on interfaces:
+{{{
+    interface [
+        NamedConstructor=Audio()
+    ] HTMLAudioElement {
+    }
+}}}
+
+The semantics is the same as [Constructor], except that JavaScript can make a DOM object not by "new HTMLAudioElement(...)" but by "Audio()".
+
+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) ===
+
+Summary: They allow to write custom bindings for constructors.
+
+Usage: They can specified on interfaces.
+Regarding [ConstructorParameters], the possible usage is [ConstructorParameters=X], where X is the maximum number of arguments of the constructor:
+{{{
+    interface [
+        CustomConstructor,
+        ConstractorParameters=4
+    ] XXX {
+    }
+}}}
+
+We should minimize the number of custom bindings as less as possible.
+Before using [CustomConstructor], you should doubly consider if you really need custom bindings.
+You are recommended to modify code generators to avoid using [Custom].
+
+Before explaining the details, let us clarify the relationship of these IDL attributes.
+
+ * [JSCustomConstructor] on an interface indicates that you want to write JavaScriptCore custom bindings for the constructor.
+ * [V8CustomConstructor] on an interface indicates that you want to write V8 custom bindings for the constructor.
+ * [CustomConstructor] is equivalent to [JSCustomConstructor] and [V8CustomConstructor].
+
+For example, if you specify [Constructor, JSCustomConstructor],
+then the constructor is generated only for V8 and you need to write JavaScriptCore custom bindings for the constructor.
+
+How to write custom bindings are different between JavaScriptCore and V8.
+
+ * JavaScriptCore
+Consider the following example:
+{{{
+    interface [
+        CustomConstructor,
+        ConstructorParameters=2
+    ] XXX {
+    }
+}}}
+You need to prepare WebCore/bindings/js/JSXXXCustom.cpp and write custom bindings:
+{{{
+    EncodedJSValue JSC_HOST_CALL JSXXXConstructor::constructJSSharedWorker(ExecState* exec)
+    {
+        ...;
+    }
+}}}
+Refer to WebCore/bindings/js/JSXXXCustom.cpp for more details.
+
+ * V8
+Consider the following example:
+{{{
+    interface [
+        CustomConstructor,
+        ConstructorParameters=2
+    ] XXX {
+    }
+}}}
+You need to prepare WebCore/bindings/v8/custom/V8XXXConstructor.cpp and write custom bindings:
+{{{
+    v8::Handle<v8::Value> V8XXX::constructorCallback(const v8::Arguments& args)
+    {
+        ...;
+    }
+}}}
+Refer to WebCore/bindings/v8/custom/V8XXXConstructor.cpp for more details.
+
+X of [ConstructorParameters=X] is the maximum number of arguments, including optional arguments.
+For example, if the constructor signature is [Constructor(in int a, in int b, in [Optional] int c, in [Optional] int d)], then X is 4.
+You do not need to specify [ConstructorParameters] if the interface does not have any of [JSCustomConstructor], [V8CustomConstructor] or [CustomConstructor].
 
 === * [Conditional](i,m,a) ===
 
+Summary: It inserts "#if ENABLE(SOME_FLAG) ... #endif" into the generated code.
+
+Usage: It can be specified on interfaces, methods and attributes:
+{{{
+    interface [
+        Conditional=INDEXED_DATABASE
+    ] XXX {
+    }
+}}}
+{{{
+    interface XXX {
+        attribute [Conditional=INDEXED_DATABASE] DOMString str;
+        [Conditional=INDEXED_DATABASE] void open();
+    }
+}}}
+
+[Conditional] is used to enable/disable the generated code based on the flag.
+If the flag is enabled, the generated code is compiled. Otherwise, the generated code is not compiled.
+Whether a flag is enabled or disabled is controlled by Tools/Scripts/build-webkit.
+
+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) ===
 
+Summary: In Chromium/V8, we can enable/disable a flag at runtime.
+
+Usage: The possible usage is [V8EnabledAtRuntime] or [V8EnabledAtRuntime=X],
+where X is an arbitrary string which you want to use for identifying the flag getter.
+It can be specified on interfaces, methods and attributes:
+{{{
+    interface [
+        V8EnabledAtRuntime
+    ] XXX {
+    }
+}}}
+{{{
+    interface XXX {
+        attribute [V8EnabledAtRuntime] DOMString str1;
+        attribute [V8EnabledAtRuntime=foo] DOMString str2;
+        [V8EnabledAtRuntime] void open1();
+        [V8EnabledAtRuntime=foo] void open2();
+    }
+}}}
+
+In Chromium/V8, we can enable/disable flags in the about:flags page.
+To make interfaces/methods/attributes controllable through about:flags, you can specify [V8EnabledAtRuntime].
+
+If [V8EnabledAtRuntime] is specified on an interface,
+it means that [V8EnabledAtRuntime] is specified on all attributes and methods on the interface....;
+
+If you add [V8EnabledAtRuntime], you need to write "flag-binding" code
+in WebCore/bindings/generic/RuntimeEnabledFeatures.h, WebCore/bindings/generic/RuntimeEnabledFeatures.cpp
+and WebKit/chromium/src/WebRuntimeFeatures.cpp.
+
+The method name of a flag getter in WebCore/bindings/generic/RuntimeEnabledFeatures.h
+is determined by the name of interfaces/methods/attributes.
+You can change the method name by using [V8EnabledAtRuntime=X].
+Refer to WebCore/bindings/generic/RuntimeEnabledFeatures.h, WebCore/bindings/generic/RuntimeEnabledFeatures.cpp
+and WebKit/chromium/src/WebRuntimeFeatures.cpp for more details.
+
 === * [CustomToJSObject](i), [JSCustomToJSObject](i), [V8CustomToJSObject](i) ===
 
+Summary: It allows us to write custom 
+
+Usage: 
+
 === * [CheckDomainSecurity](i), [DoNotCheckDomainSecurity](m,a), [DoNotCheckDomainSecurityOnGetter](a), [DoNotCheckDomainSecurityOnSetter](a) ===
 
 === * [IndexedGetter](i), [CustomIndexedGetter](i) ===
 
-=== * [NamedGetter](i), [NamedCustomGetter](i), [NamedCustomSetter](i) ===
+=== * [NamedGetter](i), [CustomNamedGetter](i), [CustomNamedSetter](i) ===
 
 === * [EventTarget](i) ===
@@ -682 +829 @@
 === * [IsWorkerContext](i) ===
 
+Summary: It indicates that the interface is a WorkerContext-related interface.
+
+Usage: It can be specified on WorkerContext-related interfaces:
+{{{
+    interface [
+        IsWorkerContext
+    ] SharedWorkerContext {
+        ...;
+    }
+}}}
+
+
 === * [CustomCall](i) ===
 
@@ -716 +875 @@
 Might be deprecated. Discussion is on-going.
 
-=== * [CustomGetOwnPropertySlot], [ConstructorParameters], [ReplaceableConstructor], [ExtendsDOMGlobalObject], [IsIndex], [V8DoNotCheckSignature], [NumericIndexedGetter] ===
+=== * [CustomGetOwnPropertySlot], [ReplaceableConstructor], [ExtendsDOMGlobalObject], [IsIndex], [V8DoNotCheckSignature], [NumericIndexedGetter] ===
 
 Will be deprecated. Discussion is on-going.