Changes between Version 94 and Version 95 of WebKitIDL


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

Use more monospace

Legend:

Unmodified
Added
Removed
Modified

  • WebKitIDL

    v94 v95  
    607607Whether `[Reflect]` should be specified or not depends on the spec of each attribute.
    608608
    609 == [Replaceable](a) == #Replaceable
     609== `[Replaceable]`(a) == #Replaceable
    610610
    611611 * [http://dev.w3.org/2006/webapi/WebIDL/#Replaceable The spec of Replaceable]
    612612
    613 Summary: [Replaceable] controls if a given attribute is "replaceable" or not.
    614 
    615 Usage: [Replaceable] can be specified on attributes:
     613Summary: `[Replaceable]` controls if a given attribute is "replaceable" or not.
     614
     615Usage: `[Replaceable]` can be specified on attributes:
    616616{{{
    617617    interface DOMWindow {
    … …  
    623623If you delete the new value, then the original value still remains.
    624624
    625 Specifically, without [Replaceable], the attribute behaves as follows:
     625Specifically, without `[Replaceable]`, the attribute behaves as follows:
    626626{{{
    627627    window.screenX; // Evaluates to 0
    … …  
    632632}}}
    633633
    634 With [Replaceable], the attribute behaves as follows:
     634With `[Replaceable]`, the attribute behaves as follows:
    635635{{{
    636636    window.screenX; // Evaluates to 0
    … …  
    641641}}}
    642642
    643 Whether [Replaceable] should be specified or not depends on the spec of each attribute.
    644 
    645 == [Deletable](a), [NotEnumerable](a), [V8ReadOnly](a) == #Deletable
     643Whether `[Replaceable]` should be specified or not depends on the spec of each attribute.
     644
     645== `[Deletable]`(a), `[NotEnumerable]`(a), `[V8ReadOnly]`(a) == #Deletable
    646646
    647647 * [http://www.ecma-international.org/publications/files/ECMA-ST/Ecma-262.pdf The spec of Writable, Enumerable and Configurable (Section 8.6.1)]
    648648
    649 Summary: They control Writability, Enumerability and Configurability of attributes.
     649Summary: They control `Writability`, `Enumerability` and `Configurability` of attributes.
    650650
    651651Usage: They can be specified on attributes:
    … …  
    656656}}}
    657657
    658 By default, non-"readonly" attributes are enumerable, writable and not deletable. "readonly" attributes are enumerable, not writable and not deletable. You can change the default behavior using [Deletable], [NotEnumerable] or [V8ReadOnly].
    659 
    660  * [Deletable] indicates that the attribute is deletable.
    661  * [NotEnumerable] indicates that the attribute is not enumerable.
    662  * [V8ReadOnly] indicates that the attribute is readonly in V8 even if the attribute is not prefixed by "readonly".
    663 
    664 == [CachedAttribute](a) == #CachedAttribute
    665 
    666 Summary: For performance optimization, [CachedAttribute] indicates that a wrapped object should be cached on a DOM object.
    667 
    668 Usage: [CachedAttribute] can be specified on attributes:
     658By default, non-"readonly" attributes are enumerable, writable and not deletable. "readonly" attributes are enumerable, not writable and not deletable. You can change the default behavior using `[Deletable]`, `[NotEnumerable]` or `[V8ReadOnly]`.
     659
     660 * `[Deletable]` indicates that the attribute is deletable.
     661 * `[NotEnumerable]` indicates that the attribute is not enumerable.
     662 * `[V8ReadOnly]` indicates that the attribute is readonly in V8 even if the attribute is not prefixed by "readonly".
     663
     664== `[CachedAttribute]`(a) == #CachedAttribute
     665
     666Summary: For performance optimization, `[CachedAttribute]` indicates that a wrapped object should be cached on a DOM object.
     667
     668Usage: `[CachedAttribute]` can be specified on attributes:
    669669{{{
    670670    interface HTMLFoo {
    … …  
    674674}}}
    675675
    676 Without [CachedAttribute], the normalValue getter works in the following way:
    677 
    678  1. HTMLFoo::normalValue() is called in WebCore.
    679  1. The result of HTMLFoo::normalValue() is passed to toJS() or toV8(), and is converted to a wrapped object.
     676Without `[CachedAttribute]`, the normalValue getter works in the following way:
     677
     678 1. `HTMLFoo::normalValue()` is called in WebCore.
     679 1. The result of `HTMLFoo::normalValue()` is passed to `toJS()` or `toV8()`, and is converted to a wrapped object.
    680680 1. The wrapped object is returned.
    681681
    682 In case where HTMLFoo::normalValue() or the operation to wrap the result is weight,
     682In case where `HTMLFoo::normalValue()` or the operation to wrap the result is weight,
    683683you can cache the wrapped object onto the DOM object.
    684 With [CachedAttribute], the normalValue getter works in the following way:
     684With `[CachedAttribute]`, the normalValue getter works in the following way:
    685685
    686686 1. If the wrapped object is cached, the cached wrapped object is returned. That's it.
    687  1. Otherwise, HTMLFoo::normalValue() is called in WebCore.
    688  1. The result of HTMLFoo::normalValue() is passed to toJS() or toV8(), and is converted to a wrapped object.
     687 1. Otherwise, `HTMLFoo::normalValue()` is called in WebCore.
     688 1. The result of `HTMLFoo::normalValue()` is passed to `toJS()` or `toV8()`, and is converted to a wrapped object.
    689689 1. The wrapped object is cached.
    690690 1. The wrapped object is returned.
    691691
    692 In particular, [CachedAttribute] will be useful for serialized values, since deserialization can be weight.
    693 Without [CachedAttribute], the serializedValue getter works in the following way:
    694 
    695  1. HTMLFoo::serializedValue() is called in WebCore.
    696  1. The result of HTMLFoo::serializedValue() is deserialized.
    697  1. The deserialized result is passed to toJS() or toV8(), and is converted to a wrapped object.
     692In particular, `[CachedAttribute]` will be useful for serialized values, since deserialization can be weight.
     693Without `[CachedAttribute]`, the serializedValue getter works in the following way:
     694
     695 1. `HTMLFoo::serializedValue()` is called in WebCore.
     696 1. The result of `HTMLFoo::serializedValue()` is deserialized.
     697 1. The deserialized result is passed to `toJS()` or `toV8()`, and is converted to a wrapped object.
    698698 1. The wrapped object is returned.
    699699
    700 In case where HTMLFoo::serializedValue(), the deserialization or the operation to wrap the result is weight,
     700In case where `HTMLFoo::serializedValue()`, the deserialization or the operation to wrap the result is weight,
    701701you can cache the wrapped object onto the DOM object.
    702 With [CachedAttribute], the serializedValue getter works in the following way:
     702With `[CachedAttribute]`, the serializedValue getter works in the following way:
    703703
    704704 1. If the wrapped object is cached, the cached wrapped object is returned. That's it.
    705  1. Otherwise, HTMLFoo::serializedValue() is called in WebCore.
    706  1. The result of HTMLFoo::serializedValue() is deserialized.
    707  1. The deserialized result is passed to toJS() or toV8(), and is converted to a wrapped object.
     705 1. Otherwise, `HTMLFoo::serializedValue()` is called in WebCore.
     706 1. The result of `HTMLFoo::serializedValue()` is deserialized.
     707 1. The deserialized result is passed to `toJS()` or `toV8()`, and is converted to a wrapped object.
    708708 1. The wrapped object is cached.
    709709 1. The wrapped object is returned.
    … …  
    714714In addition, setters always need to invalidate the cache.
    715715
    716 == [V8Unforgeable](m,a), [V8OnProto](m,a) == #V8Unforgeable
     716== `[V8Unforgeable]`(m,a), `[V8OnProto]`(m,a) == #V8Unforgeable
    717717
    718718 * [http://dev.w3.org/2006/webapi/WebIDL/#Unforgeable The spec of Unforgeable]
    … …  
    730730
    731731If you want to explicitly control where an attribute getter/setter or a method is defined in V8,
    732 you can use [V8Unforgeable] or [V8OnProto].
    733 
    734  * [V8Unforgeable] indicates that an attribute getter/setter or a method should be defined on a DOM object.
    735  * [V8OnProto] indicates that an attribute getter/setter or a method should be defined on a prototype chain.
     732you can use `[V8Unforgeable]` or `[V8OnProto]`.
     733
     734 * `[V8Unforgeable]` indicates that an attribute getter/setter or a method should be defined on a DOM object.
     735 * `[V8OnProto]` indicates that an attribute getter/setter or a method should be defined on a prototype chain.
    736736
    737737Note: As explained above, the current implementation of JSC and V8 is wrong with the Web IDL spec,
    738 and [V8Unforgeable] and [V8OnProto] are used for hack.
     738and `[V8Unforgeable]` and `[V8OnProto]` are used for hack.
    739739You should not use them unless you have a strong reason to use them.
    740740
    741 == [URL](a) == #URL
    742 
    743 Summary: [URL] indicates that a given DOMString represents a URL.
    744 
    745 Usage: [URL] can be specified on DOMString attributes only:
     741== `[URL]`(a) == #URL
     742
     743Summary: `[URL]` indicates that a given DOMString represents a URL.
     744
     745Usage: `[URL]` can be specified on DOMString attributes only:
    746746{{{
    747747    attribute [Reflect, URL] DOMString url;
    748748}}}
    749749
    750 You need to specify [URL] if a given DOMString represents a URL,
    751 since getters of URL attributes need to be realized in a special routine in WebKit, i.e. Element::getURLAttribute(...).
    752 If you forgot to specify [URL], then the attribute getter might cause a bug.
    753 
    754 == [JSWindowEventListener](a) FIXME == #JSWindowEventListener
     750You need to specify `[URL]` if a given DOMString represents a URL,
     751since getters of URL attributes need to be realized in a special routine in WebKit, i.e. `Element::getURLAttribute(...)`.
     752If you forgot to specify `[URL]`, then the attribute getter might cause a bug.
     753
     754== `[JSWindowEventListener]`(a) FIXME == #JSWindowEventListener
    755755
    756756Summary: ADD SUMMARY
    757757
    758 Usage: [JSWindowEventListener] can be specified on EventListener attributes only:
     758Usage: `[JSWindowEventListener]` can be specified on `EventListener` attributes only:
    759759{{{
    760760    attribute [JSWindowEventListener] EventListener onload;
    … …  
    763763ADD EXPLANATIONS
    764764
    765 == [Constructor](i), [CallWith](i,m,a), [ConstructorRaisesException](i) == #Constructor
     765== `[Constructor]`(i), `[CallWith]`(i,m,a), `[ConstructorRaisesException]`(i) == #Constructor
    766766
    767767 * [http://dev.w3.org/2006/webapi/WebIDL/#Constructor The spec of Constructor]
    768768
    769 Summary: [Constructor] indicates that the interface should have constructor, i.e. "new XXX()".
    770 [CallWith] and [ConstructorRaisesException] adds information when the constructor callback is called in WebCore.
    771 
    772 Usage: [Constructor], [CallWith] and [ConstructorRaisesException] can be specified on interfaces:
     769Summary: `[Constructor]` indicates that the interface should have constructor, i.e. "new XXX()".
     770`[CallWith]` and `[ConstructorRaisesException]` adds information when the constructor callback is called in WebCore.
     771
     772Usage: `[Constructor]`, `[CallWith]` and `[ConstructorRaisesException]` can be specified on interfaces:
    773773{{{
    774774    interface [
    … …  
    780780}}}
    781781
    782 [Constructor(float x, float y, DOMString str)] means that the interface has a constructor
    783 and the constructor signature is (float x, float y, DOMString str).
     782`[Constructor(float x, float y, DOMString str)]` means that the interface has a constructor
     783and the constructor signature is `(float x, float y, DOMString str)`.
    784784Specifically, JavaScript can create a DOM object of XXX by the following code:
    785785{{{
    786786    var x = new XXX(1.0, 2.0, "hello");
    787787}}}
    788 Then XXX::create(float x, float y, String str) is called in WebCore.
     788Then `XXX::create(float x, float y, String str)` is called in WebCore.
    789789That way WebCore needs to implement the following method as a constructor callback:
    790790{{{
    … …  
    795795}}}
    796796
    797 [Constructor()] is equivalent to [Constructor].
    798 
    799 If XXX::create(...) can throw Exception, you can use [ConstructorRaisesException].
    800 With [ConstructorRaisesException], a placeholder for ExceptionCode is added to the tail argument of XXX::create(...).
     797`[Constructor()]` is equivalent to `[Constructor]`.
     798
     799If `XXX::create(...)` can throw Exception, you can use `[ConstructorRaisesException]`.
     800With `[ConstructorRaisesException]`, a placeholder for ExceptionCode is added to the tail argument of `XXX::create(...)`.
    801801{{{
    802802    PassRefPtr<XXX> XXX::create(float x, float y, String str, ExceptionCode& ec)
    … …  
    810810}}}
    811811
    812 If XXX::create(...) needs additional information like ScriptExecutionContext and ScriptState,
    813 you can specify [CallWith=ScriptExecutionContext|ScriptState].
    814 Then XXX::create(...) can have the following signature:
     812If `XXX::create(...)` needs additional information like ScriptExecutionContext and ScriptState,
     813you can specify `[CallWith=ScriptExecutionContext|ScriptState]`.
     814Then `XXX::create(...)` can have the following signature:
    815815{{{
    816816    PassRefPtr<XXX> XXX::create(ScriptExecutionContext* context, ScriptState* state, float x, float y, String str)
    … …  
    822822Please see [#CallWith another [CallWith] section] for more details.
    823823
    824 Note that [CallWith=...] arguments are added at the head of XXX::create(...)'s arguments,
    825 and the ExceptionCode argument is added at the tail of XXX::create(...)'s arguments.
     824Note that `[CallWith=...]` arguments are added at the head of `XXX::create(...)`'s arguments,
     825and the ExceptionCode argument is added at the tail of `XXX::create(...)`'s arguments.
    826826
    827827Whether you should allow an interface to have constructor depends on the spec of the interface.
    828828
    829 Note: Currently [Constructor(...)] does not yet support optional arguments w/o defaults. It just supports optional [Default=Undefined] or optional [Default=NullString].
     829Note: Currently `[Constructor(...)]` does not yet support optional arguments w/o defaults. It just supports `[Default=Undefined] optional` or `[Default=NullString] optional`.
    830830
    831831== [ConstructorTemplate](i), [InitializedByEventConstructor](a) == #ConstructorTemplate