Changes between Version 93 and Version 94 of WebKitIDL


Ignore:
Timestamp:
May 8, 2013 12:44:56 AM (11 years ago)
Author:
Christophe Dumez
Comment:

Use more monospace

Legend:

Unmodified
Added
Removed
Modified

  • WebKitIDL

    v93 v94  
    324324 * [http://www.w3.org/TR/2012/CR-WebIDL-20120419/#Clamp The spec of Clamp]
    325325
    326 Summary: [Clamp] indicates that when an ECMAScript Number is converted to the IDL type, out of range values will be clamped to the range of valid values,
     326Summary: `[Clamp]` indicates that when an ECMAScript Number is converted to the IDL type, out of range values will be clamped to the range of valid values,
    327327rather than using the operators that use a modulo operation (ToInt32, ToUint32, etc.).
    328328
    329 Usage: The [Clamp] extended attribute MUST NOT appear on a read only attribute, or an attribute, operation argument or dictionary member
     329Usage: The `[Clamp]` extended attribute MUST NOT appear on a read only attribute, or an attribute, operation argument or dictionary member
    330330that is not of an integer type.
    331331
    … …  
    347347}}}
    348348
    349 Calling the non-[Clamp] version of setColor() uses ToUint8 to coerce the Numbers to octets.
    350 Hence calling context.setColor(-1, 255, 257) is equivalent to calling setColor(255, 255, 1).
    351 
    352 Calling the [Clamp] version of setColor() uses clampTo() to coerce the Numbers to octets.
    353 Hence calling context.setColor(-1, 255, 257) is equivalent to calling setColorClamped(0, 255, 255).
    354 
    355 == [Custom](m,a), [JSCustom](m,a), [V8Custom](m,a), [CustomGetter](a), [JSCustomGetter](a), [V8CustomGetter](a), [CustomSetter](a), [JSCustomSetter](a), [V8CustomSetter](a) == #Custom
     349Calling the non-`[Clamp]` version of `setColor()` uses ToUint8 to coerce the Numbers to octets.
     350Hence calling `context.setColor(-1, 255, 257)` is equivalent to calling `setColor(255, 255, 1)`.
     351
     352Calling the `[Clamp]` version of `setColor()` uses `clampTo()` to coerce the Numbers to octets.
     353Hence calling `context.setColor(-1, 255, 257)` is equivalent to calling `setColorClamped(0, 255, 255)`.
     354
     355== `[Custom]`(m,a), `[JSCustom]`(m,a), `[V8Custom]`(m,a), `[CustomGetter]`(a), `[JSCustomGetter]`(a), `[V8CustomGetter]`(a), `[CustomSetter]`(a), `[JSCustomSetter]`(a), `[V8CustomSetter]`(a) == #Custom
    356356
    357357Summary: They allow you to write bindings code manually as you like.
    358358
    359 Usage: [Custom], [JSCustom] and [V8Custom] can be specified on methods or attributes. [CustomGetter], [JSCustomGetter], [V8CustomGetter], [CustomSetter], [JSCustomSetter], [V8CustomSetter] can be specified on attributes:
     359Usage: `[Custom]`, `[JSCustom]` and `[V8Custom]` can be specified on methods or attributes. `[CustomGetter]`, `[JSCustomGetter]`, `[V8CustomGetter]`, `[CustomSetter]`, `[JSCustomSetter]`, `[V8CustomSetter]` can be specified on attributes:
    360360{{{
    361361    [Custom] void func();
    … …  
    364364
    365365We should minimize the number of custom bindings as much as possible, since they are likely to be buggy.
    366 Before using [Custom], you should doubly consider if you really need custom bindings.
    367 You are recommended to modify code generators to avoid using [Custom].
     366Before using `[Custom]`, you should doubly consider if you really need custom bindings.
     367You are recommended to modify code generators to avoid using `[Custom]`.
    368368
    369369Before explaining the details, let us clarify the relationship of these IDL attributes.
    370370
    371  * [JSCustom] on a method indicates that you can write JavaScriptCore custom bindings for the method.
    372  * [V8Custom] on a method indicates that you can write V8 custom bindings for the method.
    373  * [Custom] on a method is equivalent to [JSCustom, V8Custom].
    374  * [JSCustomGetter] or [JSCustomSetter] on an attribute indicates that you can write JavaScriptCore custom bindings for the attribute getter or setter.
    375  * [V8CustomGetter] or [V8CustomSetter] on an attribute indicates that you can write V8 custom bindings for the attribute getter or setter.
    376  * [JSCustom] on an attribute is equivalent to [JSCustomGetter, JSCustomSetter].
    377  * [V8Custom] on an attribute is equivalent to [V8CustomGetter, V8CustomSetter].
    378  * [Custom] on an attribute is equivalent to [JSCustom, V8Custom], i.e. [JSCustomGetter, JSCustomSetter, V8CustomGetter, V8CustomSetter].
    379 
    380 For example, if you want to write custom bindings only for an attribute getter of JavaScriptCore and V8 and an attribute setter of JavaScriptCore, you can specify [CustomGetter, JSCustomSetter].
     371 * `[JSCustom]` on a method indicates that you can write JavaScriptCore custom bindings for the method.
     372 * `[V8Custom]` on a method indicates that you can write V8 custom bindings for the method.
     373 * `[Custom]` on a method is equivalent to `[JSCustom, V8Custom]`.
     374 * `[JSCustomGetter]` or `[JSCustomSetter]` on an attribute indicates that you can write JavaScriptCore custom bindings for the attribute getter or setter.
     375 * `[V8CustomGetter]` or `[V8CustomSetter]` on an attribute indicates that you can write V8 custom bindings for the attribute getter or setter.
     376 * `[JSCustom]` on an attribute is equivalent to `[JSCustomGetter, JSCustomSetter]`.
     377 * `[V8Custom]` on an attribute is equivalent to `[V8CustomGetter, V8CustomSetter]`.
     378 * `[Custom]` on an attribute is equivalent to `[JSCustom, V8Custom]`, i.e. `[JSCustomGetter, JSCustomSetter, V8CustomGetter, V8CustomSetter]`.
     379
     380For example, if you want to write custom bindings only for an attribute getter of JavaScriptCore and V8 and an attribute setter of JavaScriptCore, you can specify `[CustomGetter, JSCustomSetter]`.
    381381
    382382How to write custom bindings is different between JavaScriptCore and V8 or between a method and an attribute getter/setter, as follows:
    … …  
    480480Note: ObjC, GObject and CPP bindings do not support custom bindings.
    481481
    482 == [CallWith](i,m,a) == #CallWith
    483 
    484 Summary: [CallWith] indicates that the bindings code calls a WebCore method with additional information.
    485 
    486 Usage: The possible usage is [CallWith=X1|X2|X3|...], where X1, X2, X3, ... is "ScriptExecutionContext", "ScriptState", "ScriptArguments" or "CallStack".
     482== `[CallWith]`(i,m,a) == #CallWith
     483
     484Summary: `[CallWith]` indicates that the bindings code calls a WebCore method with additional information.
     485
     486Usage: The possible usage is `[CallWith=X1|X2|X3|...]`, where X1, X2, X3, ... is "ScriptExecutionContext", "ScriptState", "ScriptArguments" or "CallStack".
    487487"ScriptExecutionContext", "ScriptState" and "CallStack" can be specified on methods or attributes,
    488488but "ScriptArguments" can be specified on methods only:
    … …  
    497497}}}
    498498
    499 Note: [CallWith] can be also specified on interfaces but it has a different meaning.
    500 Refer to [#Constructor the [Constructor] section] for [CallWith] on interfaces.
     499Note: `[CallWith]` can be also specified on interfaces but it has a different meaning.
     500Refer to [#Constructor the `[Constructor]` section] for `[CallWith]` on interfaces.
    501501
    502502In case of func1(...), HTMLFoo::func1(ScriptExecutionContext* context, int a, int b) is called in WebCore.
    … …  
    509509In this way, the additional information is added at the head of normal arguments.
    510510The order of additional information is "ScriptExecutionContext", "ScriptState", "ScriptArguments", and then "CallStack",
    511 despite the order specified in [CallWith=X1|X2|X3|...].
    512 For example, in case of func4(...), HTMLFoo::func3(ScriptArguments* arguments, ScriptCallStack* callstack, int a, int b) is called in WebCore.
    513 
    514 == [StrictTypeChecking](m,a,p) FIXME == #StrictTypeChecking
     511despite the order specified in `[CallWith=X1|X2|X3|...]`.
     512For example, in case of `func4(...)`, `HTMLFoo::func3(ScriptArguments* arguments, ScriptCallStack* callstack, int a, int b)` is called in WebCore.
     513
     514== `[StrictTypeChecking]`(m,a,p) FIXME == #StrictTypeChecking
    515515
    516516Summary: ADD SUMMARY
    517517
    518 Usage: [StrictTypeChecking] can be specified on methods and attributes:
     518Usage: `[StrictTypeChecking]` can be specified on methods and attributes:
    519519{{{
    520520    attribute [StringTypeChecking] float x;
    … …  
    524524ADD EXPLANATIONS
    525525
    526 V8 and JSC: [StrictTypeChecking] can also be applied to a DOMString parameter in an overloaded method to make the
     526V8 and JSC: `[StrictTypeChecking]` can also be applied to a DOMString parameter in an overloaded method to make the
    527527overload resolution only match for ECMAScript types null, undefined, string or object - and not number or boolean.
    528528This is to permit overloads which are not "distinguishable" in WebIDL, for example:
    … …  
    535535}}}
    536536
    537 == [ReturnNewObject](m,a) == #ReturnNewObject
    538 
    539 Summary: [ReturnNewObject] controls whether WebCore can return a cached wrapped object or WebCore needs to return a newly created wrapped object every time.
    540 
    541 Usage: [ReturnNewObject] can be specified on methods or attributes:
     537== `[ReturnNewObject]`(m,a) == #ReturnNewObject
     538
     539Summary: `[ReturnNewObject]` controls whether WebCore can return a cached wrapped object or WebCore needs to return a newly created wrapped object every time.
     540
     541Usage: `[ReturnNewObject]` can be specified on methods or attributes:
    542542{{{
    543543    attribute [ReturnNewObject] Node node;
    … …  
    545545}}}
    546546
    547 Without [ReturnNewObject], JavaScriptCore and V8 cache a wrapped object for performance.
    548 For example, consider the case where node.firstChild is accessed:
    549 
    550  1. Node::firstChild() is called in WebCore.
    551  1. The result of Node::firstChild() is passed to toJS() or toV8().
    552  1. toJS() or toV8() checks if a wrapped object of the result is already cached on the node.
     547Without `[ReturnNewObject]`, JavaScriptCore and V8 cache a wrapped object for performance.
     548For example, consider the case where `node.firstChild` is accessed:
     549
     550 1. `Node::firstChild()` is called in WebCore.
     551 1. The result of `Node::firstChild()` is passed to `toJS()` or `toV8()`.
     552 1. `toJS()` or `toV8()` checks if a wrapped object of the result is already cached on the node.
    553553 1. If cached, the cached wrapped object is returned. That's it.
    554  1. Otherwise, toJS() or toV8() creates the wrapped object of the result.
     554 1. Otherwise, `toJS()` or `toV8()` creates the wrapped object of the result.
    555555 1. The created wrapped object is cached on the node.
    556556 1. The wrapped object is returned.
    557557
    558558On the other hand, if you do not want to cache the wrapped object and want to create the wrapped object every time,
    559 you can specify [ReturnNewObject].
    560 
    561 == [ImplementedAs](m,a) == #ImplementedAs
    562 
    563 Summary: [ImplementedAs] specifies a method name in WebCore, if the method name in an IDL file and the method name in WebCore are different.
    564 
    565 Usage: The possible usage is [ImplementedAs=XXX], where XXX is a method name in WebCore.
    566 [ImplementedAs] can be specified on methods:
     559you can specify `[ReturnNewObject]`.
     560
     561== `[ImplementedAs]`(m,a) == #ImplementedAs
     562
     563Summary: `[ImplementedAs]` specifies a method name in WebCore, if the method name in an IDL file and the method name in WebCore are different.
     564
     565Usage: The possible usage is `[ImplementedAs=XXX]`, where `XXX` is a method name in WebCore.
     566`[ImplementedAs]` can be specified on methods:
    567567{{{
    568568    [ImplementedAs=deleteFunction] void delete();
    … …  
    572572Basically a method name in WebCore should be the same as the method name in an IDL file.
    573573That being said, sometimes you cannot use the same method name; e.g. "delete" is reserved for a C++ keyword.
    574 In such cases, you can explicitly specify the method name in WebCore by [ImplementedAs].
    575 You should avoid using [ImplementedAs] as much as possible though.
    576 
    577 == [Reflect](a) == #Reflect
     574In such cases, you can explicitly specify the method name in WebCore by `[ImplementedAs]`.
     575You should avoid using `[ImplementedAs]` as much as possible though.
     576
     577== `[Reflect]`(a) == #Reflect
    578578
    579579 * [http://www.whatwg.org/specs/web-apps/current-work/multipage/common-dom-interfaces.html#reflect The spec of Reflect]
    580580
    581 Summary: [Reflect] indicates that a given attribute should reflect the values of a corresponding content attribute.
    582 
    583 Usage: The possible usage is [Reflect] or [Reflect=X], where X is the name of a corresponding content attribute.
    584 [Reflect] can be specified on attributes:
     581Summary: `[Reflect]` indicates that a given attribute should reflect the values of a corresponding content attribute.
     582
     583Usage: The possible usage is `[Reflect]` or `[Reflect=X]`, where `X` is the name of a corresponding content attribute.
     584`[Reflect]` can be specified on attributes:
    585585{{{
    586586    interface Element {
    … …  
    596596Here 'id' and 'class' are content attributes.
    597597
    598 If a given attribute in an IDL file is marked as [Reflect],
     598If a given attribute in an IDL file is marked as `[Reflect]`,
    599599it indicates that the attribute getter returns the value of the corresponding content attribute
    600600and that the attribute setter sets the value of the corresponding content attribute.
    … …  
    602602
    603603If the name of the corresponding content attribute is different from the attribute name in an IDL file,
    604 you can specify the content attribute name by [Reflect=X].
    605 For example, in case of [Reflect=class], if 'div.className="barClass"' is evaluated, then "barClass" is set to the 'class' content attribute.
    606 
    607 Whether [Reflect] should be specified or not depends on the spec of each attribute.
     604you can specify the content attribute name by `[Reflect=X]`.
     605For example, in case of `[Reflect=class]`, if `'div.className="barClass"'` is evaluated, then "barClass" is set to the 'class' content attribute.
     606
     607Whether `[Reflect]` should be specified or not depends on the spec of each attribute.
    608608
    609609== [Replaceable](a) == #Replaceable