Changes between Version 122 and Version 123 of WebKitIDL

Timestamp:

Jun 10, 2013, 4:25:40 AM (12 years ago)

Author:

Christophe Dumez

Comment:

Add documentation for RaisesException, harmonize with Blink IDL

WebKitIDL

@@ -22 +22 @@
  - [#CachedAttribute CachedAttribute(a)][[br]]
  - [#JSWindowEventListener JSWindowEventListener(a)][[br]]
- - [#Constructor Constructor(i), CallWith(i,m,a), ConstructorRaisesException(i)][[br]]
+ - [#Constructor Constructor(i), CallWith(i,m,a)][[br]]
  - [#ConstructorTemplate ConstructorTemplate(i), InitializedByEventConstructor(a)][[br]]
  - [#NamedConstructor NamedConstructor(i)][[br]]
@@ -56 +56 @@
  - [#NoInterfaceObject NoInterfaceObject(i), GlobalContext(i)][[br]]
  - [#EnabledAtRuntime EnabledAtRuntime(i)][[br]]
- - [#RaisesException GetterRaisesException(a), SetterRaisesException(a)][[br]]
+ - [#RaisesException RaisesException(i,m) GetterRaisesException(a), SetterRaisesException(a)][[br]]
 
 = Overview = #Overview
@@ -649 +649 @@
 ADD EXPLANATIONS
 
-== `[Constructor]`(i), `[CallWith]`(i,m,a), `[ConstructorRaisesException]`(i) == #Constructor
+== `[Constructor]`(i), `[CallWith]`(i,m,a) == #Constructor
 
  * [http://dev.w3.org/2006/webapi/WebIDL/#Constructor The spec of Constructor]
 
 Summary: `[Constructor]` indicates that the interface should have constructor, i.e. "new XXX()".
-`[CallWith]` and `[ConstructorRaisesException]` adds information when the constructor callback is called in WebCore.
-
-Usage: `[Constructor]`, `[CallWith]` and `[ConstructorRaisesException]` can be specified on interfaces:
+`[CallWith]`adds information when the constructor callback is called in WebCore.
+
+Usage: `[Constructor]` and `[CallWith]` can be specified on interfaces:
 {{{
     [
         Constructor(float x, float y, DOMString str),
-        ConstructorRaisesException,
         CallWith=ScriptExecutionContext|ScriptState
     ] interface XXX {
@@ -682 +681 @@
 
 `[Constructor()]` is equivalent to `[Constructor]`.
-
-If `XXX::create(...)` can throw Exception, you can use `[ConstructorRaisesException]`.
-With `[ConstructorRaisesException]`, a placeholder for ExceptionCode is added to the tail argument of `XXX::create(...)`.
-{{{
-    PassRefPtr<XXX> XXX::create(float x, float y, String str, ExceptionCode& ec)
-    {
-        ...;
-        if (...) {
-            ec = TYPE_MATCH_ERR;
-            return 0;
-        }
-    }
-}}}
 
 If `XXX::create(...)` needs additional information like ScriptExecutionContext and ScriptState,
@@ -1496 +1482 @@
 }}}
 
-== `[GetterRaisesException]`(a), `[SetterRaisesException]`(a) == #RaisesException
+== `[RaisesException]`(i,m), `[GetterRaisesException]`(a), `[SetterRaisesException]`(a) == #RaisesException
 
 Standard: This is a non-standard attribute.
 
-Summary: Indicates that the attribute getter / setter may raise exceptions.
-
-The generator will pass by reference an additional "ExceptionCode" parameter to the corresponding implementation method so that an exception code can be returned.
-
-Usage: `[GetterRaisesException]` / `[SetterRaisesException]` can be specified on attributes.
-
+Summary: Tells the code generator to append an ExceptionCode& argument when calling the WebCore implementation.
+
+Implementations may assign a DOMException code to this reference parameter, and the generated binding code will create and throw the appropriate exception type.
+
+Usage: [RaisesException] can be specified on methods and interfaces, and [GetterRaisesException] and [SetterRaisesException] can be specified on attributes. On methods and attributes, the IDL looks like:
 {{{
     interface XXX {
-        [GetterRaisesException] attribute DOMString a;
-        [SetterRaisesException] attribute DOMString b;
-        [GetterRaisesException, SetterRaisesException] attribute DOMString c;
-    };
-}}}
+        [GetterRaisesException, SetterRaisesException] attribute long count;
+        [RaisesException] void foo();
+    };
+}}}
+
+And the WebCore implementations would look like:
+{{{
+    long XXX::count(ExceptionCode& ec) {
+        if (...) {
+            ec = TYPE_MISMATCH_ERROR;
+            return;
+        }
+        ...;
+    }
+
+    void XXX::setCount(long value, ExceptionCode& ec) {
+        if (...) {
+            ec = TYPE_MISMATCH_ERROR;
+            return;
+        }
+        ...;
+    }
+
+    void XXX::foo(ExceptionCode& ec) {
+        if (...) {
+            ec = TYPE_MISMATCH_ERROR;
+            return;
+        }
+        ...;
+    };
+}}}
+
+If [RaisesException] is specified on an interface and [Constructor] is also specified then an ExceptionCode& argument is added when calling the XXX::create(...) constructor callback.
+{{{
+    [
+        Constructor(float x),
+        RaisesException
+    ]
+    interface XXX {
+        ...
+    };
+}}}
+
+WebCore needs to implement the following method as a constructor callback:
+{{{
+PassRefPtr<XXX> XXX::create(float x, ExceptionCode& ec)
+{
+        ...;
+        if (...) {
+            ec = TYPE_MATCH_ERR;
+            return 0;
+        }
+        ...;
+    }
+}}}