Changes between Version 92 and Version 93 of WebKitIDL

Timestamp:

May 8, 2013 12:36:26 AM (11 years ago)

Author:

Christophe Dumez

Comment:

Start using monospace for IDL extended attributes

WebKitIDL

@@ -99 +99 @@
  * appendChild(...) and addEventListener(...) are '''method'''s of the Node interface.
  * type, listener and useCapture are '''parameter'''s of the Node interface.
- * [JSCustomHeader], [CustomToJSObject], [TreatReturnedNullStringAs=Null], [Custom] and [CustomReturn] are '''IDL attribute'''s.
+ * `[JSCustomHeader]`, `[CustomToJSObject]`, `[TreatReturnedNullStringAs=Null]`, `[Custom]` and `[CustomReturn]` are '''IDL attribute'''s.
 
 Note: These terminologies are not aligned with the Web IDL spec.
@@ -238 +238 @@
  * IDL attributes for custom bindings are prefixed by "Custom".
 
-For example, [JSNoStaticTables], [CustomGetter], [V8CustomGetter], etc.
+For example, `[JSNoStaticTables]`, `[CustomGetter]`, `[V8CustomGetter]`, etc.
 
 = IDL attributes = #IDLAttributes
@@ -244 +244 @@
 In 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.
 
-== [TreatNullAs](a,p), [TreatUndefinedAs](a,p) == #TreatNullAs
+== `[TreatNullAs]`(a,p), `[TreatUndefinedAs]`(a,p) == #TreatNullAs
 
  * [http://dev.w3.org/2006/webapi/WebIDL/#TreatNullAs The spec of TreatNullAs] (Note: The WebKit behavior explained below is different from the spec)
@@ -251 +251 @@
 Summary: They control the behavior when a JavaScript null or undefined is passed to a DOMString attribute or parameter.
 
-Usage: The possible usage is [TreatNullAs=NullString] or [TreatUndefinedAs=NullString].
+Usage: The possible usage is `[TreatNullAs=NullString]` or `[TreatUndefinedAs=NullString]`.
 They can be specified on DOMString attributes or DOMString parameters only:
 {{{
@@ -258 +258 @@
 }}}
 
-[TreatNullAs=NullString] indicates that if a JavaScript null is passed to the attribute or parameter,
+`[TreatNullAs=NullString]` indicates that if a JavaScript null is passed to the attribute or parameter,
 then it is converted to a WebKit null string, for which both String::IsEmpty() and String::IsNull() will return true.
-Without [TreatNullAs=NullString], a JavaScript null is converted to a WebKit string "null".
-
-[TreatNullAs=NullString] in WebKit corresponds to [TreatNullAs=EmptyString] in the Web IDL spec.
-Unless the spec specifies [TreatNullAs=EmptyString], you should not specify [TreatNullAs=NullString] in WebKit.
-
-[TreatUndefinedAs=NullString] indicates that if a JavaScript undefined is passed to the attribute or parameter,
+Without `[TreatNullAs=NullString]`, a JavaScript null is converted to a WebKit string "null".
+
+`[TreatNullAs=NullString]` in WebKit corresponds to `[TreatNullAs=EmptyString]` in the Web IDL spec.
+Unless the spec specifies `[TreatNullAs=EmptyString]`, you should not specify `[TreatNullAs=NullString]` in WebKit.
+
+`[TreatUndefinedAs=NullString]` indicates that if a JavaScript undefined is passed to the attribute or parameter,
 then it is converted to a WebKit null string, for which both String::IsEmpty() and String::IsNull() will return true.
-Without [TreatUndefinedAs=NullString], a JavaScript undefined is converted to a WebKit string "undefined".
-
-[TreatUndefinedAs=NullString] in WebKit corresponds to [TreatUndefinedAs=EmptyString] in the Web IDL spec.
-Unless the spec specifies [TreatUndefinedAs=EmptyString], you should not specify [TreatUndefinedAs=NullString] in WebKit.
-
-Note: For now the sole usage of [TreatUndefinedAs=NullString] is not allowed.
-[TreatUndefinedAs=NullString] must be used with [TreatNullAs=NullString], i.e. [TreatNullAs=NullString, TreatUndefinedAs=NullString].
-
-== [TreatReturnedNullStringAs](m,a) == #TreatReturnedNullStringAs
-
-Summary: [TreatReturnedNullStringAs] controls the behavior when a WebKit null string is returned from the WebCore implementation.
-
-Usage: The possible usage is [TreatReturnedNullStringAs=Null], [TreatReturnedNullStringAs=Undefined] or [TreatReturnedNullStringAs=False].
+Without `[TreatUndefinedAs=NullString]`, a JavaScript undefined is converted to a WebKit string "undefined".
+
+`[TreatUndefinedAs=NullString]` in WebKit corresponds to `[TreatUndefinedAs=EmptyString]` in the Web IDL spec.
+Unless the spec specifies `[TreatUndefinedAs=EmptyString]`, you should not specify `[TreatUndefinedAs=NullString]` in WebKit.
+
+Note: For now the sole usage of `[TreatUndefinedAs=NullString]` is not allowed.
+`[TreatUndefinedAs=NullString]` must be used with `[TreatNullAs=NullString]`, i.e. `[TreatNullAs=NullString, TreatUndefinedAs=NullString]`.
+
+== `[TreatReturnedNullStringAs]`(m,a) == #TreatReturnedNullStringAs
+
+Summary: `[TreatReturnedNullStringAs]` controls the behavior when a WebKit null string is returned from the WebCore implementation.
+
+Usage: The possible usage is `[TreatReturnedNullStringAs=Null]`, `[TreatReturnedNullStringAs=Undefined]` or `[TreatReturnedNullStringAs=False]`.
 They can be specified on DOMString attributes or methods that return a DOMString value:
 {{{
@@ -286 +286 @@
 }}}
 
- * [TreatReturnedNullStringAs=Null] indicates that if the returned DOMString is a WebKit null string, the returned value is treated as a JavaScript null.
- * [TreatReturnedNullStringAs=Undefined] indicates that if the returned DOMString is a WebKit null string, the returned value is treated as a JavaScript undefined.
- * [TreatReturnedNullStringAs=False] indicates that if the returned DOMString is a WebKit null string, the returned value is treated as a JavaScript false.
-
-Without [TreatReturnedNullStringAs=...], if the returned DOMString is a WebKit null string, then the returned value is treated as a JavaScript empty string ''.
-
-Note that what should be specified on [TreatReturnedNullStringAs=...] depends on the spec of each attribute or method.
-
-== [Default](p) == #Default
-
-Summary: [Default] allows specifying the default values for optional parameters to simplify WebCore implementations which otherwise require overloads.
-
-Standard: In Web IDL, [Default=NullString] is written as "type identifier = default", e.g. optional DOMString? str = null
-
-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:
+ * `[TreatReturnedNullStringAs=Null]` indicates that if the returned DOMString is a WebKit null string, the returned value is treated as a JavaScript null.
+ * `[TreatReturnedNullStringAs=Undefined]` indicates that if the returned DOMString is a WebKit null string, the returned value is treated as a JavaScript undefined.
+ * `[TreatReturnedNullStringAs=False]` indicates that if the returned DOMString is a WebKit null string, the returned value is treated as a JavaScript false.
+
+Without `[TreatReturnedNullStringAs=...]`, if the returned DOMString is a WebKit null string, then the returned value is treated as a JavaScript empty string ''.
+
+Note that what should be specified on `[TreatReturnedNullStringAs=...]` depends on the spec of each attribute or method.
+
+== `[Default]`(p) == #Default
+
+Summary: `[Default]` allows specifying the default values for optional parameters to simplify WebCore implementations which otherwise require overloads.
+
+Standard: In Web IDL, `[Default=NullString]` is written as `"type identifier = default"`, e.g. `optional DOMString? str = null`
+
+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:
 
 {{{
@@ -312 +312 @@
 The 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.
 
-The difference between optional and [Default=Undefined] optional is whether the WebCore implementation has overloaded methods or not, as explained below.
-
-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.
-
-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).
-
-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.
-
-== [Clamp](a,p) == #Clamp
+The difference between optional and `[Default=Undefined]` optional is whether the WebCore implementation has overloaded methods or not, as explained below.
+
+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.
+
+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)`.
+
+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.
+
+== `[Clamp]`(a,p) == #Clamp
 
  * [http://www.w3.org/TR/2012/CR-WebIDL-20120419/#Clamp The spec of Clamp]