Changes between Version 51 and Version 52 of WebKitIDL


Ignore:
Timestamp:
Feb 20, 2012, 5:10:46 AM (13 years ago)
Author:
haraken@chromium.org
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • WebKitIDL

    v51 v52  
    278278
    279279Usage: The possible usage is [TreatReturnedNullStringAs=Null], [TreatReturnedNullStringAs=Undefined] or [TreatReturnedNullStringAs=False].
    280 They can be specified on DOMString attributes or methods which return a DOMString value:
     280They can be specified on DOMString attributes or methods that return a DOMString value:
    281281{{{
    282282    attribute [TreatReturnedNullStringAs=Null] DOMString str;
    … …  
    558558Summary: ADD SUMMARY
    559559
    560 Usage: [Reflect] can be specified on attributes.
     560Usage: [Reflect] can be specified on attributes:
    561561{{{
    562562    attribute [Reflect] DOMString str;
    … …  
    727727 * [http://old.nabble.com/Things-missing-from-Web-IDL-for-HTML5-td24873773.html Easy explanation of Supplemental]
    728728
    729 Summary: [Supplemental] helps WebKit modularization. [Supplemental] makes it possible to add XXX's APIs (e.g. XXX=WebAudio, WebSocket, Blob, GamePad, ...etc) without modifying code outside of WebCore/Modules/XXX/. This helps make XXX a "self-contained module".
     729Summary: [Supplemental] helps WebKit modularization.
     730[Supplemental] makes it possible to add XXX's APIs (e.g. XXX=WebAudio, WebSocket, Blob, GamePad, ...etc) without modifying code outside of WebCore/Modules/XXX/.
     731This helps make XXX a "self-contained module".
    730732
    731733Usage: The possible usage is
    … …  
    736738    };
    737739}}}
    738 where XXX implements YYY. [Supplemental] can be specified on interfaces.
    739 
    740 Here is an example. Without [Supplemental], if you want to add XXX's attributes or methods to DOMWindow,
     740where XXX implements YYY.
     741[Supplemental] can be specified on interfaces.
     742
     743Without [Supplemental], if you want to add XXX's attributes or methods to DOMWindow,
    741744
    742745 * you need to modify WebCore/page/DOMWindow.idl to add the XXX's attributes or methods
    743746
    744  * you need to modify WebCore/page/DOMWindow.{h,cpp} to add the C++ implementation of the attribute getters and setters or the method callbacks.
     747 * you need to modify WebCore/page/DOMWindow.{h,cpp} to add the WebCore implementation of the attribute getters and setters or the method callbacks.
    745748
    746749On the other hand, in the modularized world with [Supplemental], you just need to modify the code under WebCore/Modules/XXX/:
    … …  
    753756       Supplemental=DOMWindow    // The attributes and methods of this interface are exposed as those of DOMWindow.
    754757   ] DOMWindowXXX {
    755        attribute foo;
     758       attribute int foo;
    756759       void bar();
    757760   };
    … …  
    761764
    762765{{{
    763    DOMWindowXXX::foo(...) { ... }   // The C++ implementation of the foo attribute getter.
    764    DOMWindowXXX::setFoo(...) { ... }   // The C++ implementation of the foo attribute setter.
    765    DOMWindowXXX::bar(...) { ... }   // The C++ implementation of the bar method callback.
    766 }}}
    767 
    768 As shown above, [Supplemental=DOMWindow] indicates that all the attributes and methods of DOMWindowXXX should be exposed on DOMWindow, but should be implemented in DOMWindowXXX. In this way, you can implement the attributes and methods without modifying code of DOMWindow.{h,cpp,idl}.
    769 
    770 If you want to add APIs whose implementations are likely to be independent from WebCore, it is strongly recommended to put the APIs and .h/.cpp files into WebCore/Modules/XXX/ using [Supplemental].
    771 
    772 ==  [Constructor](i), [CallWith](i,m,a), [ConstructorRaisesException](i) == #Constructor
     766   DOMWindowXXX::foo(...) { ... }   // The WebCore implementation of the foo attribute getter.
     767   DOMWindowXXX::setFoo(...) { ... }   // The WebCore implementation of the foo attribute setter.
     768   DOMWindowXXX::bar(...) { ... }   // The WebCore implementation of the bar() method callback.
     769}}}
     770
     771As shown above, [Supplemental=DOMWindow] indicates that all the attributes and methods of DOMWindowXXX should be exposed on DOMWindow,
     772but should be implemented in DOMWindowXXX.
     773In this way, you can implement the attributes and methods without modifying code of DOMWindow.{h,cpp,idl}.
     774
     775If you want to add APIs whose implementations are likely to be independent from WebCore,
     776it is strongly recommended to put the APIs and .h/.cpp files into WebCore/Modules/XXX/ using [Supplemental].
     777On the other hand, if the implementations need to touch WebCore much,
     778the APIs might not be good candidates for [Supplemental].
     779
     780== [Constructor](i), [CallWith](i,m,a), [ConstructorRaisesException](i) == #Constructor
    773781
    774782 * [http://dev.w3.org/2006/webapi/WebIDL/#Constructor The spec of Constructor]
    775783
    776 Summary: It indicates that the interface should have constructor "new XXX()".
     784Summary: [Constructor] indicates that the interface should have constructor, i.e. "new XXX()".
     785[CallWith] and [ConstructorRaisesException] adds information when the constructor callback is called in WebCore.
    777786
    778787Usage: [Constructor], [CallWith] and [ConstructorRaisesException] can be specified on interfaces:
    … …  
    786795}}}
    787796
    788 [Constructor(in float x, in float y, in DOMString str)] means that the interface has constructor
     797[Constructor(in float x, in float y, in DOMString str)] means that the interface has a constructor
    789798and the constructor signature is (in float x, in float y, in DOMString str).
    790 Specifically, JavaScript can generate a DOM object of XXX by the following code:
     799Specifically, JavaScript can create a DOM object of XXX by the following code:
    791800{{{
    792801    var x = new XXX(1.0, 2.0, "hello");
    793802}}}
    794803Then XXX::create(float x, float y, String str) is called in WebCore.
    795 Specifically, WebCore needs to implement the following method:
     804That way WebCore needs to implement the following method as a constructor callback:
    796805{{{
    797806    PassRefPtr<XXX> XXX::create(float x, float y, String str)
    … …  
    803812[Constructor()] is equivalent to [Constructor].
    804813
    805 If the WebCore method can throw Exception, you can use [ConstructorRaisesException].
    806 With [ConstructorRaisesException], an ExceptionCode argument is added to the tail argument of XXX::create(...).
     814If XXX::create(...) can throw Exception, you can use [ConstructorRaisesException].
     815With [ConstructorRaisesException], a placeholder for ExceptionCode is added to the tail argument of XXX::create(...).
    807816{{{
    808817    PassRefPtr<XXX> XXX::create(float x, float y, String str, ExceptionCode& ec)
    … …  
    816825}}}
    817826
    818 If the WebCore method needs additional information like ScriptExecutionContext and ScriptState,
    819 you can specify it by [CallWith=ScriptExecutionContext|ScriptState].
    820 Then the WebCore method can have the following signature:
     827If XXX::create(...) needs additional information like ScriptExecutionContext and ScriptState,
     828you can specify [CallWith=ScriptExecutionContext|ScriptState].
     829Then XXX::create(...) can have the following signature:
    821830{{{
    822831    PassRefPtr<XXX> XXX::create(ScriptExecutionContext* context, ScriptState* state, float x, float y, String str)
    … …  
    826835}}}
    827836You can retrieve document or frame from ScriptExecutionContext.
    828 Please see another [CallWith] section for more details.
    829 
    830 Note that [CallWith=...] arguments are added at the head of the WebCore method arguments,
    831 and the ExceptionCode argument is added at the tail of the WebCore method arguments.
     837Please see [#CallWith another [CallWith] section] for more details.
     838
     839Note that [CallWith=...] arguments are added at the head of XXX::create(...)'s arguments,
     840and the ExceptionCode argument is added at the tail of XXX::create(...)'s arguments.
    832841
    833842Whether you should allow an interface to have constructor depends on the spec of the interface.
    834843
    835 ==  [ConstructorTemplate](i), [InitializedByEventConstructor](a) == #ConstructorTemplate
     844== [ConstructorTemplate](i), [InitializedByEventConstructor](a) == #ConstructorTemplate
    836845
    837846Summary: They are used for Event constructors.
    838847
    839848Usage: The possible usage is [ConstructorTemplate=Event].
    840 [ConstructorTemplate=Event] can be specified on Event interfaces.
     849[ConstructorTemplate=Event] can be specified on Event interfaces only.
    841850[InitializedByEventConstructor] can be specified on attributes in the Event interfaces:
    842851{{{
    … …  
    849858}}}
    850859
    851 Since constructors for Event interfaces require special binding,
     860Since constructors for Event interfaces require special bindings,
    852861you need to use [ConstructorTemplate=Event] instead of normal [Constructor].
    853862
    854863If you specify [ConstructorTemplate=Event] on FooEvent,
    855 JavaScript can make a DOM object of FooEvent in the following code:
     864JavaScript can create a DOM object of FooEvent in the following code:
    856865{{{
    857866    var e = new FooEvent("type", { bubbles: true, cancelable: true });
    858867}}}
    859868Then FooEvent::create(...) is called in WebCore.
    860 Specifically, WebCore needs to implement the following method:
    861 {{{
    862     PassRefPtr<FooEvent> FooEvent::create(const AtomicString& type, const ProgressEventInit& initializer)
     869Specifically, WebCore needs to implement the following method as a constructor callback:
     870{{{
     871    PassRefPtr<FooEvent> FooEvent::create(const AtomicString& type, const FooEventInit& initializer)
    863872    {
    864873        ...;
    … …  
    867876
    868877[InitializedByEventConstructor] should be specified on all the attributes
    869 which needs to be initialized by the constructor.
    870 Which attributes needs initialization is defined in the spec.
     878that needs to be initialized by the constructor.
     879Which attributes need initialization is defined in the spec of each Event interface.
    871880For example, look at [http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html#event the spec of Event].
    872 EventInit dictionary has bubbles and cancelable, and thus bubbles and cancelable are the only attributes
    873 that needs to be initialized by the Event constructor.
     881The EventInit dictionary has bubbles and cancelable, and thus bubbles and cancelable are the only attributes
     882that need to be initialized by the Event constructor.
    874883In other words, in case of Event, you should specify [InitializedByEventConstructor] on bubbles and cancelable.
    875884
    … …  
    878887 * [http://dev.w3.org/2006/webapi/WebIDL/#NamedConstructor The spec of NamedConstructor]
    879888
    880 Summary: If the interface name XXX and "new YYY()" name are different (i.e. XXX != YYY), you can use [NamedConstructor].
    881 
    882 Usage: The possible usage of [NamedConstructor] is [NamedConstructor=YYY].
     889Summary: If you want to allow JavaScript to create a DOM object of XXX using a different name constructor
     890(i.e. allow JavaScript to create an XXX object using "new YYY()", where YYY != XXX), you can use [NamedConstructor].
     891
     892Usage: The possible usage is [NamedConstructor=YYY].
    883893[NamedConstructor] can be specified on interfaces:
    884894{{{
    … …  
    889899}}}
    890900
    891 The semantics is the same as [Constructor], except that JavaScript can make a DOM object not by "new HTMLAudioElement(...)" but by "Audio()".
    892 
    893 Whether you should allow an interface to have a named constructor depends on the spec of the interface.
     901The semantics is the same as [Constructor], except that JavaScript can make a DOM object not by "new HTMLAudioElement()" but by "Audio()".
     902
     903Whether you should allow an interface to have a named constructor or not depends on the spec of each interface.
    894904
    895905==  [CustomConstructor](i), [JSCustomConstructor](i), [V8CustomConstructor](i), [ConstructorParameters](i) == #CustomConstructor
    … …  
    897907Summary: They allow you to write custom bindings for constructors.
    898908
    899 Usage: They can specified on interfaces.
     909Usage: They can be specified on interfaces.
    900910Regarding [ConstructorParameters], the possible usage is [ConstructorParameters=X], where X is the maximum number of arguments of the constructor:
    901911{{{
    902912    interface [
    903913        CustomConstructor,
    904         ConstractorParameters=4
     914        ConstructorParameters=4
    905915    ] XXX {
    906916    };
    … …  
    913923Before explaining the details, let us clarify the relationship of these IDL attributes.
    914924
    915  * [JSCustomConstructor] on an interface indicates that you want to write JavaScriptCore custom bindings for the constructor.
    916  * [V8CustomConstructor] on an interface indicates that you want to write V8 custom bindings for the constructor.
     925 * [JSCustomConstructor] on an interface indicates that you can write JavaScriptCore custom bindings for the constructor.
     926 * [V8CustomConstructor] on an interface indicates that you can write V8 custom bindings for the constructor.
    917927 * [CustomConstructor] is equivalent to [JSCustomConstructor, V8CustomConstructor].
    918928
    … …  
    920930then the constructor is generated only for V8 and you need to write JavaScriptCore custom bindings for the constructor.
    921931
    922 How to write custom bindings are different between JavaScriptCore and V8.
     932How to write custom bindings is different between JavaScriptCore and V8.
    923933
    924934 * JavaScriptCore: Consider the following example:
    … …  
    931941    };
    932942}}}
    933 You need to prepare WebCore/bindings/js/JSXXXCustom.cpp and write custom bindings:
    934 {{{
    935     EncodedJSValue JSC_HOST_CALL JSXXXConstructor::constructJSSharedWorker(ExecState* exec)
     943Then you can write custom bindings in WebCore/bindings/js/JSXXXCustom.cpp:
     944{{{
     945    EncodedJSValue JSC_HOST_CALL JSXXXConstructor::constructJSXXX(ExecState* exec)
    936946    {
    937947        ...;
    … …  
    949959    };
    950960}}}
    951 You need to prepare WebCore/bindings/v8/custom/V8XXXConstructor.cpp and write custom bindings:
     961Then you can write custom bindings in WebCore/bindings/v8/custom/V8XXXConstructorCustom.cpp:
    952962{{{
    953963    v8::Handle<v8::Value> V8XXX::constructorCallback(const v8::Arguments& args)
    … …  
    956966    }
    957967}}}
    958 Refer to WebCore/bindings/v8/custom/V8XXXConstructor.cpp for more details.
     968Refer to WebCore/bindings/v8/custom/V8XXXConstructorCustom.cpp for more details.
    959969
    960970X of [ConstructorParameters=X] is the maximum number of arguments, including optional arguments.
    961 For example, if the constructor signature is [Constructor(in int a, in int b, in [Optional] int c, in [Optional] int d)], then X is 4.
     971For example, if a constructor signature is [Constructor(in int a, in int b, in [Optional] int c, in [Optional] int d)], then X is 4.
     972
    962973You do not need to specify [ConstructorParameters] if the interface does not have any of [JSCustomConstructor], [V8CustomConstructor] or [CustomConstructor].
    963974
    964 ==  [Conditional](i,m,a) == #Conditional
    965 
    966 Summary: It inserts "#if ENABLE(SOME_FLAG) ... #endif" into the generated code.
     975== [Conditional](i,m,a) == #Conditional
     976
     977Summary: [Conditional] inserts "#if ENABLE(SOME_FLAG) ... #endif" into the generated code.
    967978
    968979Usage: [Conditional] can be specified on interfaces, methods and attributes:
    … …  
    980991}}}
    981992
    982 [Conditional] is used to enable/disable the generated code based on the flag.
    983 If the flag is enabled, the generated code is compiled. Otherwise, the generated code is not compiled.
    984 Whether a flag is enabled or disabled is controlled by Tools/Scripts/build-webkit.
    985 
    986 If [Conditional] is specified on an interface, it means that [Conditional] is specified on all attributes and methods on the interface.
     993[Conditional] is used to enable or disable the generated code based on a "flag".
     994If a given flag is enabled, the generated code is compiled. Otherwise, the generated code is not compiled.
     995Whether a flag is enabled or disabled is controlled (mostly) by Tools/Scripts/build-webkit.
     996
     997If [Conditional] is specified on an interface, it means that [Conditional] is specified on all attributes and methods of the interface.
    987998
    988999==  [V8EnabledAtRuntime](i,m,a) == #V8EnabledAtRuntime
    9891000
    990 Summary: In Chromium/V8, you can enable/disable a flag at runtime.
     1001Summary: In Chromium/V8, you can enable or disable a flag at runtime.
    9911002
    9921003Usage: The possible usage is [V8EnabledAtRuntime] or [V8EnabledAtRuntime=X],
    993 where X is an arbitrary string which you want to use for identifying the flag getter.
    994 [V8EnabledAtRuntime] can be specified on interfaces, methods and attributes:
     1004where X is an arbitrary string that you want to use for identifying the flag getter.
     1005[V8EnabledAtRuntime] can be specified on interfaces, methods or attributes:
    9951006{{{
    9961007    interface [
    … …  
    10081019}}}
    10091020
    1010 In Chromium/V8, you can enable/disable flags in the about:flags page.
    1011 To make interfaces/methods/attributes controllable through about:flags, you can specify [V8EnabledAtRuntime].
    1012 
    1013 If [V8EnabledAtRuntime] is specified on an interface,
    1014 it means that [V8EnabledAtRuntime] is specified on all attributes and methods on the interface....;
    1015 
    1016 If you add [V8EnabledAtRuntime], you need to write "flag-binding" code
     1021To make interfaces, methods or attributes enabled or disabled through the about:flags page of Chromium/V8, you can specify [V8EnabledAtRuntime].
     1022
     1023If you specify [V8EnabledAtRuntime], you need to write "flag-binding" code
    10171024in WebCore/bindings/generic/RuntimeEnabledFeatures.h, WebCore/bindings/generic/RuntimeEnabledFeatures.cpp
    10181025and WebKit/chromium/src/WebRuntimeFeatures.cpp.
    10191026
    1020 The method name of a flag getter in WebCore/bindings/generic/RuntimeEnabledFeatures.h
    1021 is determined by the name of interfaces/methods/attributes.
    1022 You can change the method name by using [V8EnabledAtRuntime=X].
     1027The method names of a "flag-binding" code in WebCore/bindings/generic/RuntimeEnabledFeatures.h
     1028are determined by the name of interfaces, methods or attributes by default.
     1029You can change the method names by using [V8EnabledAtRuntime=X], where X becomes the method name base.
    10231030Refer to WebCore/bindings/generic/RuntimeEnabledFeatures.h, WebCore/bindings/generic/RuntimeEnabledFeatures.cpp
    10241031and WebKit/chromium/src/WebRuntimeFeatures.cpp for more details.
    10251032
     1033If [V8EnabledAtRuntime] is specified on an interface,
     1034it means that [V8EnabledAtRuntime] is specified on all the attributes and methods of the interface,
     1035
    10261036==  [CustomToJSObject](i), [JSCustomToJSObject](i), [V8CustomToJSObject](i) == #CustomToJSObject
    10271037
    … …  
    10361046}}}
    10371047
    1038  * [JSCustomToJSObject] on an interface indicates that you want to write custom toJS().
    1039  * [V8CustomToJSObject] on an interface indicates that you want to write custom toV8().
     1048 * [JSCustomToJSObject] on an interface indicates that you can write custom toJS().
     1049 * [V8CustomToJSObject] on an interface indicates that you can write custom toV8().
    10401050 * [CustomToJSObject] is equivalent to [JSCustomToJSObject, V8CustomToJSObject].
    10411051
    1042 By default, toJS() and toV8() are automatically generated in JSXXX.h and JSXXX.cpp or V8XXX.h and V8XXX.cpp.
    1043 With [CustomToJSObject] or [JSCustomToJSObject], you can write custom toJS() WebCore/bindings/js/JSXXXCustom.cpp:
     1052By default (i.e. without [*CustomToJSObject]), toJS() and toV8() are generated automatically.
     1053
     1054 * With [CustomToJSObject] or [JSCustomToJSObject], you can write custom toJS() in WebCore/bindings/js/JSXXXCustom.cpp:
     1055
    10441056{{{
    10451057    JSValue toJS(ExecState* exec, JSDOMGlobalObject* globalObject, XXX* impl)
    … …  
    10481060    }
    10491061}}}
    1050 With [CustomToJSObject] or [V8CustomToJSObject], you can write custom toV8() WebCore/bindings/v8/custom/V8XXXCustom.cpp:
     1062 * With [CustomToJSObject] or [V8CustomToJSObject], you can write custom toV8() in WebCore/bindings/v8/custom/V8XXXCustom.cpp:
     1063
    10511064{{{
    10521065    v8::Handle<v8::Value> toV8(XXX* impl, bool forceNewObject)
    … …  
    10561069}}}
    10571070
    1058 ==  [CheckSecurity](i), [DoNotCheckSecurity](m,a), [DoNotCheckSecurityOnGetter](a), [DoNotCheckSecurityOnSetter](a) == #CheckSecurity
    1059 
    1060 Summary: It checks if a given Frame access is allowed or not, in terms of security.
     1071== [CheckSecurity](i), [DoNotCheckSecurity](m,a), [DoNotCheckSecurityOnGetter](a), [DoNotCheckSecurityOnSetter](a) == #CheckSecurity
     1072
     1073Summary: They check whether a given access is allowed or not, in terms of the same-origin security policy.
    10611074
    10621075Usage: [CheckSecurity] can be specified on interfaces.
    1063 [DoNotCheckSecurity] can be specified on methods or attributes which belong to interfaces which have [CheckSecurity].
     1076[DoNotCheckSecurity] can be specified on methods or attributes that belong to interfaces that have [CheckSecurity].
    10641077[DoNotCheckSecurityOnGetter] and [DoNotCheckSecurityOnSetter] can be specified on attributes
    1065 which belong to interfaces which have [CheckSecurity]:
     1078that belong to interfaces that have [CheckSecurity]:
    10661079{{{
    10671080    interface [
    … …  
    10771090}}}
    10781091
    1079 Consider the case where you access window.parent from inside iframe which comes from a different origin.
     1092Consider the case where you access window.parent from inside an iframe that comes from a different origin.
    10801093While it is allowed to access window.parent, it is not allowed to access window.parent.document.
    10811094In such cases, you need to specify [CheckSecurity] in order to check
    1082 whether a given Frame is allowed to access the attribute or method.
     1095whether a given DOM object is allowed to access the attribute or method, in terms of the same-origin security policy.
    10831096This is really important for security.
    10841097
    1085 If you specify [CheckSecurity] on an interface, the security check is enabled on all the attributes and methods in the interface.
    1086 To disable the security check for some attribute or method, you can use
    1087 [DoNotCheckSecurity], [DoNotCheckSecurityOnGetter] or [DoNotCheckSecurityOnSetter].
     1098If you specify [CheckSecurity] on an interface, the security check is enabled on all the attributes and methods of the interface.
     1099To disable the security check for particular attributes or methods,
     1100you can use [DoNotCheckSecurity], [DoNotCheckSecurityOnGetter] or [DoNotCheckSecurityOnSetter].
    10881101
    10891102 * [DoNotCheckSecurity] on a method disables the security check for the method.
    … …  
    10951108==  [CheckSecurityForNode](m,a) == #CheckSecurityForNode
    10961109
    1097 Summary: It checks if a given Node access is allowed in terms of security.
    1098 
    1099 Usage: [CheckSecurityForNode] can be specified on methods and attributes:
     1110Summary: [CheckSecurityForNode] checks whether a given access to Node is allowed or not, in terms of the same-origin security policy.
     1111
     1112Usage: [CheckSecurityForNode] can be specified on methods or attributes:
    11001113{{{
    11011114    attribute [CheckSecurityForNode] Node contentDocument;
    … …  
    11031116}}}
    11041117
    1105 In terms of security, node.contentDocument should return undefined if the parent frame and the child frame are from different origins.
    1106 If the security check is needed, you should specify [CheckSecurityForNode].
     1118In terms of the same-origin security policy, node.contentDocument should return undefined if the parent frame and the child frame are from different origins.
     1119If the security check is necessary, you should specify [CheckSecurityForNode].
    11071120This is really important for security.
    11081121
    1109 ==  [IndexedGetter](i) == #IndexedGetter
     1122== [IndexedGetter](i) == #IndexedGetter
    11101123
    11111124 * [http://dev.w3.org/2006/webapi/WebIDL/#idl-indexed-properties The spec of indexed properties] (Note: The WebKit behavior explained below is different from the spec)
    … …  
    11221135
    11231136Indexed getters define the behavior when XXX[i] is evaluated.
    1124 The bindings code is generated automatically so that XXX[i] behaves equivalent to XXX.item(i).
    1125 
    1126 ==  [CustomIndexedSetter](i) == #CustomIndexedSetter
     1137For example, if XXX is an array-type interface, it should have indexed getters (and setters).
     1138The bindings code for indexed getters is generated automatically so that XXX[i] behaves equivalent to XXX.item(i).
     1139
     1140== [CustomIndexedSetter](i) == #CustomIndexedSetter
    11271141
    11281142 * [http://dev.w3.org/2006/webapi/WebIDL/#idl-indexed-properties The spec of indexed properties] (Note: The WebKit behavior explained below is different from the spec)
    … …  
    11391153
    11401154Indexed setters define the behavior when "XXX[i] = ..." is evaluated.
    1141 [CustomIndexedSetter] allows you to write the custom bindings.
     1155For example, if XXX is an array-type interface, it should have indexed (getters and) setters.
     1156[CustomIndexedSetter] allows you to write the custom bindings, as follows.
    11421157
    11431158 * JavaScriptCore: You can write JSXXX::indexSetter(...) in WebCore/bindings/js/JSXXXCustom.cpp:
    … …  
    11491164    }
    11501165}}}
    1151  * In V8: You can write V8XXX::indexedPropertyGetter(...) in WebCore/bindings/v8/custom/V8XXXCustom.cpp:
    1152 
    1153 {{{
    1154     v8::Handle<v8::Value> V8XXX::indexedPropertyGetter(uint32_t index, const v8::AccessorInfo& info)
     1166 * In V8: You can write V8XXX::indexedPropertySetter(...) in WebCore/bindings/v8/custom/V8XXXCustom.cpp:
     1167
     1168{{{
     1169    v8::Handle<v8::Value> V8XXX::indexedPropertySetter(uint32_t index, const v8::AccessorInfo& info)
    11551170    {
    11561171        ...;
    … …  
    11721187}}}
    11731188
    1174 Named getters define the behavior when XXX.foooooooo is evaluated, where foooooooo is not an attribute of a given interface.
    1175 The bindings code is generated automatically so that XXX.foooooooo behaves equivalent to XXX.namedItem(i).
     1189Named getters define the behavior when XXX.foooooooo is evaluated, where foooooooo is not an attribute of XXX.
     1190The bindings code for named getters is generated automatically so that XXX.foooooooo behaves equivalent to XXX.namedItem(i).
    11761191
    11771192== [CustomNamedGetter](i), [CustomNamedSetter](i) == #CustomNamedGetter
    … …  
    11791194 * [http://dev.w3.org/2006/webapi/WebIDL/#idl-named-properties The spec of named properties] (Note: The WebKit behavior explained below is different from the spec)
    11801195
    1181 Summary: [CustomNamedGetter]/[CustomNamedSetter] allows you to write custom bindings for a getter/setter of named properties.
     1196Summary: [CustomNamedGetter] or [CustomNamedSetter] allows you to write custom bindings for a getter or setter of named properties.
    11821197
    11831198Usage: They can be specified on interfaces:
    … …  
    11901205}}}
    11911206
    1192 Named getters define the behavior when XXX.foooooooo is evaluated, where foooooooo is not an attribute of a given interface.
     1207Named getters define the behavior when XXX.foooooooo is evaluated, where foooooooo is not an attribute of XXX.
    11931208Named setters define the behavior when "XXX.foooooooo = ..." is evaluated.
    1194 [CustomNamedGetter] and [CustomNamedSetter] allow you to write the custom bindings.
     1209[CustomNamedGetter] or [CustomNamedSetter] allow you to write the custom bindings, as follows:
    11951210
    11961211 * [CustomNamedGetter] in JavaScriptCore: You can write JSXXX::canGetItemsForName(...) and JSXXX::nameGetter(...) in WebCore/bindings/js/JSXXXCustom.cpp:
    11971212
    11981213{{{
    1199     bool JSXXX::canGetItemsForName(ExecState*, XXX* impl, const Identifier& propertyName)
     1214    bool JSXXX::canGetItemsForName(ExecState* exec, XXX* impl, const Identifier& propertyName)
    12001215    {
    12011216        ...;
    … …  
    12101225
    12111226{{{
    1212     v8::Handle<v8::Value> V8XXX::namedPropertyGetter(v8::Local<v8::String>, v8::Local<v8::Value>, const v8::AccessorInfo&)
     1227    v8::Handle<v8::Value> V8XXX::namedPropertyGetter(v8::Local<v8::String> name, const v8::AccessorInfo& info)
    12131228    {
    12141229        ...;
    … …  
    12181233
    12191234{{{
    1220     bool JSXXX::putDelegate(ExecState* exec, const Identifier& propertyName, JSValue value, PutPropertySlot&)
     1235    bool JSXXX::putDelegate(ExecState* exec, const Identifier& propertyName, JSValue value, PutPropertySlot& slot)
    12211236    {
    12221237        ...;
    … …  
    12261241
    12271242{{{
    1228     v8::Handle<v8::Value> V8XXX::namedPropertySetter(v8::Local<v8::String>, v8::Local<v8::Value>, const v8::AccessorInfo&)
     1243    v8::Handle<v8::Value> V8XXX::namedPropertySetter(v8::Local<v8::String> name, v8::Local<v8::Value> value, const v8::AccessorInfo& info)
    12291244    {
    12301245        ...;
    … …  
    12361251Summary: ADD SUMMARY
    12371252
    1238 Usage: [EventTarget] can be specified on interfaces.
     1253Usage: [EventTarget] can be specified on interfaces:
    12391254{{{
    12401255    interface [
    … …  
    12911306Summary: ADD SUMMARY
    12921307
    1293 Usage: [V8DependentLifeTime] can be specified on interfaces.
     1308Usage: [V8DependentLifeTime] can be specified on interfaces:
    12941309{{{
    12951310    interface [
    … …  
    13981413==  [JSCustomToNativeObject](i), [JSCustomFinalize](i), [JSCustomIsReachable](i), [JSCustomMarkFunction](i), [JSCustomNamedGetterOnPrototype](i), [JSCustomPushEventHandlerScope](i), [JSCustomDefineOwnProperty](i), [JSCustomDefineOwnPropertyOnPrototype](i), [JSCustomGetOwnPropertySlotAndDescriptor](i) == #JSCustomToNativeObject
    13991414
    1400 Summary: They allow you to write custom code for the JavaScriptCore code which would be generated automatically by default.
     1415Summary: They allow you to write custom code for the JavaScriptCore code that would be generated automatically by default.
    14011416
    14021417Usage: They can be specified on interfaces:
    … …  
    15011516Summary: They force JavaScriptCore bindings to generate JavaScriptCore specific methods even if a given interface has a parent interface.
    15021517
    1503 Usage: They can be specified on interfaces which do not have a parent interface:
     1518Usage: They can be specified on interfaces that do not have a parent interface:
    15041519{{{
    15051520    interface [
    … …  
    15621577Summary: ADD SUMMARY
    15631578
    1564 Usage: [JSNoStaticTables] can be specified on interfaces.
     1579Usage: [JSNoStaticTables] can be specified on interfaces:
    15651580{{{
    15661581    interface [