Changes between Version 92 and Version 93 of WebKitIDL


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

Start using monospace for IDL extended attributes

Legend:

Unmodified
Added
Removed
Modified
  • WebKitIDL

    v92 v93  
    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] and [CustomReturn] 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.
     
    238238 * IDL attributes for custom bindings are prefixed by "Custom".
    239239
    240 For example, [JSNoStaticTables], [CustomGetter], [V8CustomGetter], etc.
     240For example, `[JSNoStaticTables]`, `[CustomGetter]`, `[V8CustomGetter]`, etc.
    241241
    242242= IDL attributes = #IDLAttributes
     
    244244In the following explanations, (i), (m), (a) or (p) means that a given 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.
    245245
    246 == [TreatNullAs](a,p), [TreatUndefinedAs](a,p) == #TreatNullAs
     246== `[TreatNullAs]`(a,p), `[TreatUndefinedAs]`(a,p) == #TreatNullAs
    247247
    248248 * [http://dev.w3.org/2006/webapi/WebIDL/#TreatNullAs The spec of TreatNullAs] (Note: The WebKit behavior explained below is different from the spec)
     
    251251Summary: They control the behavior when a JavaScript null or undefined is passed to a DOMString attribute or parameter.
    252252
    253 Usage: The possible usage is [TreatNullAs=NullString] or [TreatUndefinedAs=NullString].
     253Usage: The possible usage is `[TreatNullAs=NullString]` or `[TreatUndefinedAs=NullString]`.
    254254They can be specified on DOMString attributes or DOMString parameters only:
    255255{{{
     
    258258}}}
    259259
    260 [TreatNullAs=NullString] indicates that if a JavaScript null is passed to the attribute or parameter,
     260`[TreatNullAs=NullString]` indicates that if a JavaScript null is passed to the attribute or parameter,
    261261then it is converted to a WebKit null string, for which both String::IsEmpty() and String::IsNull() will return true.
    262 Without [TreatNullAs=NullString], a JavaScript null is converted to a WebKit string "null".
    263 
    264 [TreatNullAs=NullString] in WebKit corresponds to [TreatNullAs=EmptyString] in the Web IDL spec.
    265 Unless the spec specifies [TreatNullAs=EmptyString], you should not specify [TreatNullAs=NullString] in WebKit.
    266 
    267 [TreatUndefinedAs=NullString] indicates that if a JavaScript undefined is passed to the attribute or parameter,
     262Without `[TreatNullAs=NullString]`, a JavaScript null is converted to a WebKit string "null".
     263
     264`[TreatNullAs=NullString]` in WebKit corresponds to `[TreatNullAs=EmptyString]` in the Web IDL spec.
     265Unless the spec specifies `[TreatNullAs=EmptyString]`, you should not specify `[TreatNullAs=NullString]` in WebKit.
     266
     267`[TreatUndefinedAs=NullString]` indicates that if a JavaScript undefined is passed to the attribute or parameter,
    268268then it is converted to a WebKit null string, for which both String::IsEmpty() and String::IsNull() will return true.
    269 Without [TreatUndefinedAs=NullString], a JavaScript undefined is converted to a WebKit string "undefined".
    270 
    271 [TreatUndefinedAs=NullString] in WebKit corresponds to [TreatUndefinedAs=EmptyString] in the Web IDL spec.
    272 Unless the spec specifies [TreatUndefinedAs=EmptyString], you should not specify [TreatUndefinedAs=NullString] in WebKit.
    273 
    274 Note: For now the sole usage of [TreatUndefinedAs=NullString] is not allowed.
    275 [TreatUndefinedAs=NullString] must be used with [TreatNullAs=NullString], i.e. [TreatNullAs=NullString, TreatUndefinedAs=NullString].
    276 
    277 == [TreatReturnedNullStringAs](m,a) == #TreatReturnedNullStringAs
    278 
    279 Summary: [TreatReturnedNullStringAs] controls the behavior when a WebKit null string is returned from the WebCore implementation.
    280 
    281 Usage: The possible usage is [TreatReturnedNullStringAs=Null], [TreatReturnedNullStringAs=Undefined] or [TreatReturnedNullStringAs=False].
     269Without `[TreatUndefinedAs=NullString]`, a JavaScript undefined is converted to a WebKit string "undefined".
     270
     271`[TreatUndefinedAs=NullString]` in WebKit corresponds to `[TreatUndefinedAs=EmptyString]` in the Web IDL spec.
     272Unless the spec specifies `[TreatUndefinedAs=EmptyString]`, you should not specify `[TreatUndefinedAs=NullString]` in WebKit.
     273
     274Note: For now the sole usage of `[TreatUndefinedAs=NullString]` is not allowed.
     275`[TreatUndefinedAs=NullString]` must be used with `[TreatNullAs=NullString]`, i.e. `[TreatNullAs=NullString, TreatUndefinedAs=NullString]`.
     276
     277== `[TreatReturnedNullStringAs]`(m,a) == #TreatReturnedNullStringAs
     278
     279Summary: `[TreatReturnedNullStringAs]` controls the behavior when a WebKit null string is returned from the WebCore implementation.
     280
     281Usage: The possible usage is `[TreatReturnedNullStringAs=Null]`, `[TreatReturnedNullStringAs=Undefined]` or `[TreatReturnedNullStringAs=False]`.
    282282They can be specified on DOMString attributes or methods that return a DOMString value:
    283283{{{
     
    286286}}}
    287287
    288  * [TreatReturnedNullStringAs=Null] indicates that if the returned DOMString is a WebKit null string, the returned value is treated as a JavaScript null.
    289  * [TreatReturnedNullStringAs=Undefined] indicates that if the returned DOMString is a WebKit null string, the returned value is treated as a JavaScript undefined.
    290  * [TreatReturnedNullStringAs=False] indicates that if the returned DOMString is a WebKit null string, the returned value is treated as a JavaScript false.
    291 
    292 Without [TreatReturnedNullStringAs=...], if the returned DOMString is a WebKit null string, then the returned value is treated as a JavaScript empty string ''.
    293 
    294 Note that what should be specified on [TreatReturnedNullStringAs=...] depends on the spec of each attribute or method.
    295 
    296 == [Default](p) == #Default
    297 
    298 Summary: [Default] allows specifying the default values for optional parameters to simplify WebCore implementations which otherwise require overloads.
    299 
    300 Standard: In Web IDL, [Default=NullString] is written as "type identifier = default", e.g. optional DOMString? str = null
    301 
    302 Usage: 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:
     288 * `[TreatReturnedNullStringAs=Null]` indicates that if the returned DOMString is a WebKit null string, the returned value is treated as a JavaScript null.
     289 * `[TreatReturnedNullStringAs=Undefined]` indicates that if the returned DOMString is a WebKit null string, the returned value is treated as a JavaScript undefined.
     290 * `[TreatReturnedNullStringAs=False]` indicates that if the returned DOMString is a WebKit null string, the returned value is treated as a JavaScript false.
     291
     292Without `[TreatReturnedNullStringAs=...]`, if the returned DOMString is a WebKit null string, then the returned value is treated as a JavaScript empty string ''.
     293
     294Note that what should be specified on `[TreatReturnedNullStringAs=...]` depends on the spec of each attribute or method.
     295
     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:
    303303
    304304{{{
     
    312312The 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.
    313313
    314 The difference between optional and [Default=Undefined] optional is whether the WebCore implementation has overloaded methods or not, as explained below.
    315 
    316 In 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 
    318 In 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 
    320 The 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.
    321 
    322 == [Clamp](a,p) == #Clamp
     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.
     321
     322== `[Clamp]`(a,p) == #Clamp
    323323
    324324 * [http://www.w3.org/TR/2012/CR-WebIDL-20120419/#Clamp The spec of Clamp]