Changes between Version 95 and Version 96 of WebKitIDL


Ignore:
Timestamp:
May 8, 2013 1:01:03 AM (11 years ago)
Author:
Christophe Dumez
Comment:

Use more monospace

Legend:

Unmodified
Added
Removed
Modified

  • WebKitIDL

    v95 v96  
    829829Note: Currently `[Constructor(...)]` does not yet support optional arguments w/o defaults. It just supports `[Default=Undefined] optional` or `[Default=NullString] optional`.
    830830
    831 == [ConstructorTemplate](i), [InitializedByEventConstructor](a) == #ConstructorTemplate
     831== `[ConstructorTemplate]`(i), `[InitializedByEventConstructor]`(a) == #ConstructorTemplate
    832832
    833833Summary: They are used for Event constructors.
    834834
    835 Usage: The possible usage is [ConstructorTemplate=Event].
    836 [ConstructorTemplate=Event] can be specified on Event interfaces only.
    837 [InitializedByEventConstructor] can be specified on attributes in the Event interfaces:
     835Usage: The possible usage is `[ConstructorTemplate=Event]`.
     836`[ConstructorTemplate=Event]` can be specified on Event interfaces only.
     837`[InitializedByEventConstructor]` can be specified on attributes in the Event interfaces:
    838838{{{
    839839    interface [
    … …  
    846846
    847847Since constructors for Event interfaces require special bindings,
    848 you need to use [ConstructorTemplate=Event] instead of normal [Constructor].
    849 
    850 If you specify [ConstructorTemplate=Event] on FooEvent,
     848you need to use `[ConstructorTemplate=Event]` instead of normal `[Constructor]`.
     849
     850If you specify `[ConstructorTemplate=Event]` on FooEvent,
    851851JavaScript can create a DOM object of FooEvent in the following code:
    852852{{{
    … …  
    862862}}}
    863863
    864 [InitializedByEventConstructor] should be specified on all the attributes
     864`[InitializedByEventConstructor]` should be specified on all the attributes
    865865that needs to be initialized by the constructor.
    866866Which attributes need initialization is defined in the spec of each Event interface.
    … …  
    868868The EventInit dictionary has bubbles and cancelable, and thus bubbles and cancelable are the only attributes
    869869that need to be initialized by the Event constructor.
    870 In other words, in case of Event, you should specify [InitializedByEventConstructor] on bubbles and cancelable.
    871 
    872 == [NamedConstructor](i) == #NamedConstructor
     870In other words, in case of Event, you should specify `[InitializedByEventConstructor]` on bubbles and cancelable.
     871
     872== `[NamedConstructor]`(i) == #NamedConstructor
    873873
    874874 * [http://dev.w3.org/2006/webapi/WebIDL/#NamedConstructor The spec of NamedConstructor]
    875875
    876876Summary: If you want to allow JavaScript to create a DOM object of XXX using a different name constructor
    877 (i.e. allow JavaScript to create an XXX object using "new YYY()", where YYY != XXX), you can use [NamedConstructor].
    878 
    879 Usage: The possible usage is [NamedConstructor=YYY].
    880 [NamedConstructor] can be specified on interfaces:
     877(i.e. allow JavaScript to create an XXX object using "new YYY()", where YYY != XXX), you can use `[NamedConstructor]`.
     878
     879Usage: The possible usage is `[NamedConstructor=YYY]`.
     880`[NamedConstructor]` can be specified on interfaces:
    881881{{{
    882882    interface [
    … …  
    886886}}}
    887887
    888 The semantics is the same as [Constructor], except that JavaScript can make a DOM object not by "new HTMLAudioElement()" but by "Audio()".
     888The semantics is the same as `[Constructor]`, except that JavaScript can make a DOM object not by "new HTMLAudioElement()" but by "Audio()".
    889889
    890890Whether you should allow an interface to have a named constructor or not depends on the spec of each interface.
    891891
    892 == [CustomConstructor](i), [JSCustomConstructor](i), [V8CustomConstructor](i), [ConstructorParameters](i) == #CustomConstructor
     892== `[CustomConstructor]`(i), `[JSCustomConstructor]`(i), `[V8CustomConstructor]`(i), `[ConstructorParameters]`(i) == #CustomConstructor
    893893
    894894Summary: They allow you to write custom bindings for constructors.
    895895
    896896Usage: They can be specified on interfaces.
    897 Regarding [ConstructorParameters], the possible usage is [ConstructorParameters=X], where X is the maximum number of arguments of the constructor:
     897Regarding `[ConstructorParameters]`, the possible usage is `[ConstructorParameters=X]`, where `X` is the maximum number of arguments of the constructor:
    898898{{{
    899899    interface [
    … …  
    905905
    906906We should minimize the number of custom bindings as less as possible.
    907 Before using [CustomConstructor], you should doubly consider if you really need custom bindings.
    908 You are recommended to modify code generators to avoid using [Custom].
     907Before using `[CustomConstructor]`, you should doubly consider if you really need custom bindings.
     908You are recommended to modify code generators to avoid using `[Custom]`.
    909909
    910910Before explaining the details, let us clarify the relationship of these IDL attributes.
    911911
    912  * [JSCustomConstructor] on an interface indicates that you can write JavaScriptCore custom bindings for the constructor.
    913  * [V8CustomConstructor] on an interface indicates that you can write V8 custom bindings for the constructor.
    914  * [CustomConstructor] is equivalent to [JSCustomConstructor, V8CustomConstructor].
    915 
    916 For example, if you specify [Constructor, JSCustomConstructor],
     912 * `[JSCustomConstructor]` on an interface indicates that you can write JavaScriptCore custom bindings for the constructor.
     913 * `[V8CustomConstructor]` on an interface indicates that you can write V8 custom bindings for the constructor.
     914 * `[CustomConstructor]` is equivalent to `[JSCustomConstructor, V8CustomConstructor]`.
     915
     916For example, if you specify `[Constructor, JSCustomConstructor]`,
    917917then the constructor is generated only for V8 and you need to write JavaScriptCore custom bindings for the constructor.
    918918
    … …  
    955955Refer to WebCore/bindings/v8/custom/V8XXXConstructorCustom.cpp for more details.
    956956
    957 X of [ConstructorParameters=X] is the maximum number of arguments, including optional arguments.
    958 For example, if a constructor signature is [Constructor(int a, int b, [Default=Undefined] optional int c, [Default=DefaultIsUndefined] optional int d)], then X is 4.
    959 
    960 You do not need to specify [ConstructorParameters] if the interface does not have any of [JSCustomConstructor], [V8CustomConstructor] or [CustomConstructor].
    961 
    962 == [Conditional](i,m,a) == #Conditional
    963 
    964 Summary: [Conditional] inserts "#if ENABLE(SOME_FLAG) ... #endif" into the generated code.
    965 
    966 Usage: [Conditional] can be specified on interfaces, methods and attributes:
     957`X` of `[ConstructorParameters=X]` is the number of mandatory arguments.
     958For example, if a constructor signature is `[Constructor(int a, int b, [Default=Undefined] optional int c, [Default=DefaultIsUndefined] optional int d)]`, then `X` is 2.
     959
     960You do not need to specify `[ConstructorParameters]` if the interface does not have any of `[JSCustomConstructor]`, `[V8CustomConstructor]` or `[CustomConstructor]`.
     961
     962== `[Conditional]`(i,m,a) == #Conditional
     963
     964Summary: `[Conditional]` inserts "#if ENABLE(SOME_FLAG) ... #endif" into the generated code.
     965
     966Usage: `[Conditional]` can be specified on interfaces, methods and attributes:
    967967{{{
    968968    interface [
    … …  
    978978}}}
    979979
    980 [Conditional] is used to enable or disable the generated code based on a "flag".
     980`[Conditional]` is used to enable or disable the generated code based on a "flag".
    981981If a given flag is enabled, the generated code is compiled. Otherwise, the generated code is not compiled.
    982982Whether a flag is enabled or disabled is controlled (mostly) by Tools/Scripts/build-webkit.
    983983
    984 If [Conditional] is specified on an interface, it means that [Conditional] is specified on all attributes and methods of the interface.
    985 
    986 == [CheckSecurity](i), [DoNotCheckSecurity](m,a), [DoNotCheckSecurityOnGetter](a), [DoNotCheckSecurityOnSetter](a) == #CheckSecurity
     984If `[Conditional]` is specified on an interface, it means that `[Conditional]` is specified on all attributes and methods of the interface.
     985
     986== `[CheckSecurity]`(i), `[DoNotCheckSecurity]`(m,a), `[DoNotCheckSecurityOnGetter]`(a), `[DoNotCheckSecurityOnSetter]`(a) == #CheckSecurity
    987987
    988988Summary: They check whether a given access is allowed or not, in terms of the same-origin security policy.
    989989
    990 Usage: [CheckSecurity] can be specified on interfaces.
    991 [DoNotCheckSecurity] can be specified on methods or attributes that belong to interfaces that have [CheckSecurity].
    992 [DoNotCheckSecurityOnGetter] and [DoNotCheckSecurityOnSetter] can be specified on attributes
    993 that belong to interfaces that have [CheckSecurity]:
     990Usage: `[CheckSecurity]` can be specified on interfaces.
     991`[DoNotCheckSecurity]` can be specified on methods or attributes that belong to interfaces that have `[CheckSecurity]`.
     992`[DoNotCheckSecurityOnGetter]` and `[DoNotCheckSecurityOnSetter]` can be specified on attributes
     993that belong to interfaces that have `[CheckSecurity]`:
    994994{{{
    995995    interface [
    … …  
    10071007Consider the case where you access window.parent from inside an iframe that comes from a different origin.
    10081008While it is allowed to access window.parent, it is not allowed to access window.parent.document.
    1009 In such cases, you need to specify [CheckSecurity] in order to check
     1009In such cases, you need to specify `[CheckSecurity]` in order to check
    10101010whether a given DOM object is allowed to access the attribute or method, in terms of the same-origin security policy.
    10111011This is really important for security.
    10121012
    1013 If you specify [CheckSecurity] on an interface, the security check is enabled on all the attributes and methods of the interface.
     1013If you specify `[CheckSecurity]` on an interface, the security check is enabled on all the attributes and methods of the interface.
    10141014To disable the security check for particular attributes or methods,
    1015 you can use [DoNotCheckSecurity], [DoNotCheckSecurityOnGetter] or [DoNotCheckSecurityOnSetter].
    1016 
    1017  * [DoNotCheckSecurity] on a method disables the security check for the method.
    1018  * [DoNotCheckSecurity] on an attribute disables the security check for a getter and setter of the attribute.
    1019  * [DoNotCheckSecurityOnGetter] on an attribute disables the security check for a getter of the attribute.
    1020  * [DoNotCheckSecurityOnSetter] on an attribute disables the security check for a setter of the attribute.
    1021  * [DoNotCheckSecurity] on an attribute is equivalent to [DoNotCheckSecurityOnGetter, DoNotCheckSecurityOnSetter].
    1022 
    1023 == [CheckSecurityForNode](m,a) == #CheckSecurityForNode
    1024 
    1025 Summary: [CheckSecurityForNode] checks whether a given access to Node is allowed or not, in terms of the same-origin security policy.
    1026 
    1027 Usage: [CheckSecurityForNode] can be specified on methods or attributes:
     1015you can use `[DoNotCheckSecurity]`, `[DoNotCheckSecurityOnGetter]` or `[DoNotCheckSecurityOnSetter]`.
     1016
     1017 * `[DoNotCheckSecurity]` on a method disables the security check for the method.
     1018 * `[DoNotCheckSecurity]` on an attribute disables the security check for a getter and setter of the attribute.
     1019 * `[DoNotCheckSecurityOnGetter]` on an attribute disables the security check for a getter of the attribute.
     1020 * `[DoNotCheckSecurityOnSetter]` on an attribute disables the security check for a setter of the attribute.
     1021 * `[DoNotCheckSecurity]` on an attribute is equivalent to `[DoNotCheckSecurityOnGetter, DoNotCheckSecurityOnSetter]`.
     1022
     1023== `[CheckSecurityForNode]`(m,a) == #CheckSecurityForNode
     1024
     1025Summary: `[CheckSecurityForNode]` checks whether a given access to Node is allowed or not, in terms of the same-origin security policy.
     1026
     1027Usage: `[CheckSecurityForNode]` can be specified on methods or attributes:
    10281028{{{
    10291029    attribute [CheckSecurityForNode] Node contentDocument;
    … …  
    10311031}}}
    10321032
    1033 In terms of the same-origin security policy, node.contentDocument should return undefined if the parent frame and the child frame are from different origins.
    1034 If the security check is necessary, you should specify [CheckSecurityForNode].
     1033In terms of the same-origin security policy, `node.contentDocument` should return undefined if the parent frame and the child frame are from different origins.
     1034If the security check is necessary, you should specify `[CheckSecurityForNode]`.
    10351035This is really important for security.
    10361036