Changes between Version 90 and Version 91 of WebKitIDL


Ignore:
Timestamp:
May 8, 2013, 12:04:45 AM (12 years ago)
Author:
Christophe Dumez
Comment:

Update documentation for optional and [Default]

Legend:

Unmodified
Added
Removed
Modified

  • WebKitIDL

    v90 v91  
    1010 - [#TreatNullAs TreatNullAs(a,p), TreatUndefinedAs(a,p)][[br]]
    1111 - [#TreatReturnedNullStringAs TreatReturnedNullStringAs(m,a)][[br]]
    12  - [#Optional Optional(p)][[br]]
     12 - [#Default Default(p)][[br]]
    1313 - [#Clamp Clamp(a,p)][[br]]
    1414 - [#Custom Custom(m,a), JSCustom(m,a), V8Custom(m,a), CustomGetter(a), JSCustomGetter(a), V8CustomGetter(a), CustomSetter(a), JSCustomSetter(a), V8CustomSetter(a)][[br]]
    … …  
    8787        attribute [TreatReturnedNullStringAs=Null] DOMString nodeName;
    8888        [Custom] Node appendChild(in [CustomReturn] Node newChild);
    89         void addEventListener(in DOMString type, in EventListener listener, in [Optional] boolean useCapture);
     89        void addEventListener(DOMString type, EventListener listener, optional boolean useCapture);
    9090    };
    9191}
    … …  
    9999 * appendChild(...) and addEventListener(...) are '''method'''s of the Node interface.
    100100 * type, listener and useCapture are '''parameter'''s of the Node interface.
    101  * [JSCustomHeader], [CustomToJSObject], [TreatReturnedNullStringAs=Null], [Custom], [CustomReturn] and [Optional] are '''IDL attribute'''s.
     101 * [JSCustomHeader], [CustomToJSObject], [TreatReturnedNullStringAs=Null], [Custom] and [CustomReturn] are '''IDL attribute'''s.
    102102
    103103Note: These terminologies are not aligned with the Web IDL spec.
    … …  
    294294Note that what should be specified on [TreatReturnedNullStringAs=...] depends on the spec of each attribute or method.
    295295
    296 == [Optional](p) == #Optional
    297 
    298 Summary: [Optional] allows method overloading for methods whose argument counts are different with each other.
    299 
    300 Usage: The possible usage is [Optional], [Optional=DefaultIsUndefined] or [Optional=DefaultIsNullString].
    301 [Optional] and [Optional=DefaultIsUndefined] can be specified on parameters.
    302 [Optional=DefaultIsNullString] can be specified on DOMString parameters only:
     296== [Default](p) == #Default
     297
     298Summary: [Default] allows specifying the default values for optional parameters to simplify WebCore implementations which otherwise require overloads.
     299
     300Standard: In Web IDL, [Default=NullString] is written as "type identifier = default", e.g. optional DOMString? str = null
     301
     302Usage: The possible usages are [Default=Undefined] or [Default=NullString]. [Default=Undefined] can be specified on any optional parameter. [Default=NullString] can be specified on DOMString parameters only:
     303
    303304{{{
    304305    interface HTMLFoo {
    305         void func1(in int a, in int b, in [Optional] int c, in [Optional] int d);
    306         void func2(in int a, in int b, in [Optional=DefaultIsUndefined] int c);
    307         void func3(in int a, in int b, in [Optional=DefaultIsUndefined] DOMString c, in [Optional=DefaultIsNullString] DOMString d);
    308     };
    309 }}}
    310 
    311 The parameters marked with [Optional=...] are optional, and JavaScript can omit the parameters. Obviously, if parameter X is marked with [Optional=...], then all subsequent parameters of X should be marked with [Optional=...].
    312 
    313 The difference between [Optional] and [Optional=DefaultIsUndefined] is whether the WebCore implementation has overloaded methods or not, as explained below.
    314 
    315 In case of func1(...), if JavaScript calls func1(100, 200), then HTMLFoo::func1(int a, int b) is called in WebCore.
    316 If JavaScript calls func1(100, 200, 300), then HTMLFoo::func1(int a, int b, int c) is called in WebCore.
    317 If JavaScript calls func1(100, 200, 300, 400), then HTMLFoo::func1(int a, int b, int c, int d) is called in WebCore.
    318 In other words, if the WebCore implementation has overloaded methods, you can use [Optional].
    319 
    320 In case of func2(...), if JavaScript calls func2(100, 200), then it behaves as if JavaScript called func2(100, 200, undefined).
    321 Consequently, HTMLFoo::func2(int a, int b, int c) is called in WebCore.
    322 100 is passed to a, 200 is passed to b, and 0 is passed to c.
    323 (A JavaScript undefined is converted to 0, following the value conversion rule in the Web IDL spec.)
    324 In this way, WebCore needs to just implement func2(int a, int b, int c) and needs not to implement both func2(int a, int b) and func2(int a, int b, int c).
    325 
    326 The difference between [Optional=DefalutIsUndefined] and [Optional=DefaultIsNullString] appears only when the parameter type is DOMString.
    327 In [Optional=DefalutIsUndefined], the "supplemented" JavaScript undefined is converted to a WebKit string "undefined".
    328 On the other hand, in [Optional=DefaultIsNullString], the "supplemented" JavaScript undefined is converted to a WebKit null string.
    329 For example, if JavaScript calls func3(100, 200), then HTMLFoo::func3(int a, int b, String c, String d) is called in WebCore.
    330 At this point, 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.
    331 d.IsEmpty() and d.IsNull() return true.
     306        void func1(int a, int b, optional int c, optional int d);
     307        void func2(int a, int b, [Default=Undefined] optional int c);
     308        void func3(int a, int b, [Default=Undefined] optional DOMString c, [Default=NullString] optional DOMString d);
     309    };
     310}}}
     311
     312The parameters marked with the standard Web IDL optional qualifier are optional, and JavaScript can omit the parameters. Obviously, if parameter X is marked with optional then all subsequent parameters of X should be marked with optional.
     313
     314The difference between optional and [Default=Undefined] optional is whether the WebCore implementation has overloaded methods or not, as explained below.
     315
     316In case of func1(...), if JavaScript calls func1(100, 200), then HTMLFoo::func1(int a, int b) is called in WebCore. If JavaScript calls func1(100, 200, 300), then HTMLFoo::func1(int a, int b, int c) is called in WebCore. If JavaScript calls func1(100, 200, 300, 400), then HTMLFoo::func1(int a, int b, int c, int d) is called in WebCore. In other words, if the WebCore implementation has overloaded methods, you can use optional.
     317
     318In case of func2(...) which adds [Default=Undefined], if JavaScript calls func2(100, 200), then it behaves as if JavaScript called func2(100, 200, undefined). Consequently, HTMLFoo::func2(int a, int b, int c) is called in WebCore. 100 is passed to a, 200 is passed to b, and 0 is passed to c. (A JavaScript undefined is converted to 0, following the value conversion rule in the Web IDL spec.) In this way, WebCore needs to just implement func2(int a, int b, int c) and needs not to implement both func2(int a, int b) and func2(int a, int b, int c).
     319
     320The difference between [Default=Undefined] and [Default=NullString] appears only when the parameter type is DOMString. In [Default=Undefined]  the "supplemented" JavaScript undefined is converted to a WebKit string "undefined". On the other hand, in [Default=NullString] the "supplemented" JavaScript undefined is converted to a WebKit null string. For example, if JavaScript calls func3(100, 200), then HTMLFoo::func3(int a, int b, String c, String d) is called in WebCore. At this point, 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. d.IsEmpty() and d.IsNull() return true.
    332321
    333322== [Clamp](a,p) == #Clamp
    … …  
    838827Whether you should allow an interface to have constructor depends on the spec of the interface.
    839828
    840 Note: Currently [Constructor(...)] does not yet support [Optional] arguments. It just supports [Optional=DefaultIsUndefined] or [Optional=DefaultIsNullString].
     829Note: Currently [Constructor(...)] does not yet support optional arguments w/o defaults. It just supports optional [Default=Undefined] or optional [Default=NullString].
    841830
    842831== [ConstructorTemplate](i), [InitializedByEventConstructor](a) == #ConstructorTemplate
    … …  
    967956
    968957X of [ConstructorParameters=X] is the maximum number of arguments, including optional arguments.
    969 For example, if a constructor signature is [Constructor(in int a, in int b, in [Optional=DefaultIsUndefined] int c, in [Optional=DefaultIsUndefined] int d)], then X is 4.
     958For example, if a constructor signature is [Constructor(in int a, in int b, in [Default=Undefined] optional int c, in [Default=DefaultIsUndefined] optional int d)], then X is 4.
    970959
    971960You do not need to specify [ConstructorParameters] if the interface does not have any of [JSCustomConstructor], [V8CustomConstructor] or [CustomConstructor].
    … …  
    13721361{{{
    13731362    interface Worker {
    1374         void postMessage(in [TransferList=transfer] SerializedScriptValue data, in [Optional=DefaultIsUndefined] Array transfer);
     1363        void postMessage(in [TransferList=transfer] SerializedScriptValue data, in [Default=Undefined] optional Array transfer);
    13751364    }
    13761365}}}