W3C home > Mailing lists > Public > public-script-coord@w3.org > July to September 2011

Re: WebIDL editorial feedback

From: timeless <timeless@gmail.com>
Date: Tue, 12 Jul 2011 21:32:22 -0400
Message-ID: <CAACrNNdWFQciCfvOnAskVB4Kkv+HdKowU56T-71qqNVKPkmVLQ@mail.gmail.com>
To: public-script-coord@w3.org
> An IDL sequence value S0..n−1 of type sequence<T> is converted to an
> ECMAScript Array object as follows:

> 1.    Let A be a new Array object created as if by the expression [].

It would be somewhat nice if the array size could be set here instead
of relying on

3.3 to increase the size. I'm not sure if this is something which is

> 2.    Initialize i to be 0.
> 3.    While i < n:
> 3.1.        Let E be the result of converting Si to an ECMAScript value.
> 3.2.        Let P be the result of calling ToString(i).
> 3.3.        Call [[Put]] on A with property name P and value E.
> 3.4.        Set i to i + 1.


> whenever an Array is passed to drawPolygon a reference to it will never be kept.

s/never/not/ -- or "no reference to it will be kept after the call completes"

> // "hi" will be alerted before drawPolygon() returns.

technically it will be alerted before drawPolygon() is called, right?

> canvas.drawPolygon
>  ([false, '',
>    { valueOf: function() { alert('hi'); return 100 } }, 0,

I know the trailing semicolon is optional, but could I get you to
include it? :) --

also applies to 'throw "abc" later.

>    '50', new Number(62.5)]);

> // Modifying an Array that was passed to drawPolygon() is guaranteed not to
> // have an effect on the Canvas, since the Array is effectively passed by value.
> a[0] = 20;

This is a bad example, because afaiu, drawPolygon() is an
instantaneous function. A

better example would be a [CallBack] interface with a sample JS impl
which stashes

its value and returns it so you can confirm that it isn't change.

> The value of the internal [[Prototype]] property of an platform array
> object MUST be the Array prototype object ([ECMA-262], section 15.4.4).

This doesn't specify which global scope, I hope that's properly implied.

> The value of the internal [[Class]] property of an platform array object
> MUST be the type name of the array type.

Should 'array type' be a link?

> Platform array objects defy being fixed;

This is a strange construct. I understand it, but I think you might
want to rephrase


> if Object.freeze, Object.seal or Object.preventExtensions is called on one,

s/if/if any one of/ ?

> the function MUST throw a TypeError.

function a() { b() } function b() { throw 1; } -- is a() said to throw
1? I worry

that your must throw overspecifies who should do the throwing instead
of ensuring

that it be thrown.

> An ECMAScript value V is converted to an IDL array value of type T[] as follows:
> 1.    Initialize n to be the result of calling [[Get]] on V with property name

> 2.    Set n to ToUint32(n).
> 3.    Initialize E0..n to be a list of IDL values.

It feels like 'E' comes out of nowhere, I need to check your other
bits to see if

this is standard.

> 6. The IDL array value is a fixed length array of length n whose values are E0..n.

s/n/n-1/g ?

> var a = [4, 8, 15, 16, 23, 42];      // Numbers can be assigned into the array.
> for (var i = 0; i < 6; i++) {
>  results.numbers[i] = a[i];
> }

> results.numbers = a;                 // This has no effect, since numbers is
>                                      // read only.

This should be done before the for loop above, otherwise it's
impossible to determine

that it has no effect.

> results.numbers[0] = 6.25;           // Assigns 6 to the first element of the array
>                                      // since that is how 6.5 is converted to an
>                                      // unsigned short.

> results.numbers.slice(0, 2);         // Evaluates to an Array [4, 8].


> interface LotteryResults {
>   attribute unsigned short[] numbers;
> };

> then an Array object can be assigned to the numbers property.
> Unless the prose accompanying the interface said otherwise,
> this would result in a fixed length array of whatever length
> the Array has being assigned to the IDL attribute.
> ECMAScript

> var results = new LotteryResults();

> results.numbers.length;       // Evaluates to 6.

It would be helpful if you had a results.numbers.push() here showing
that it didn't

do anything.

> var a = [1, 3, 5];

> results.numbers = a;          // Assigns a fixed length IDL array of length 3 to
>                               // the numbers attribute.

> results.numbers;              // This now evaluates to an platform array object


>                               // that represents the fixed length IDL array,
>                               // not the Array object assigned in the previous
>                               // statement.

A `results.numbers != a` statement might be useful if that's the case.

> results.numbers.length;       // Evaluates to 3.


> Platform objects returning an ECMAScript Date object from attributes,
> operations or exception field do not hold on to a reference to the Date object.

s/on to/onto/

> Script that modifies a Date object so returned cannot affect the

s/Script/A script/

> platform object it was returned from.


> When the [AllowAny] extended attribute is present on the argument,
> that disqualification is not performed.

s/performed/applied/ ?

> If the [NoInterfaceObject] extended attribute is specified on an
> interface, then the [Constructor] extended attribute MUST NOT
> also be specified on that interface.

It would be nice if this was mentioned in the [Constructor] section too.

I guess [NamedConstructor] is ok - it would be good to mention it
(possibly even as a


> If the [OverrideBuiltins] extended attribute appears on an interface,
> it indicates that for a platform object implementing the interface,
> properties will appear to be own the object

s/own/on/ (or is it 'owned by'? -- hard to tell)

> corresponding to all of the object’s supported property names,

this is awkward/misordered. <all properties corresponding to the
object's supported

property names will appear to be on the object itself> ?

> regardless of what other properties exist on the object or its prototype chain.
> This means that named properties will always shadow any properties
> that would otherwise appear on the object.

> This is in constrast to the usual behavior, which is for named


> properties to be exposed only if there is no property with the
> same name on the object itself or somewhere on its prototype chain.

> The [OverrideBuiltins] extended attribute MUST take no argument
> and MUST NOT appear on an interface that does not define a name
> getter or that also is declared with the [ReplaceableNamedProperties]
> extended attribute.

An example with [ReplaceableNamedProperties] would be useful.

> If the [Replaceable] extended attribute appears on a read only
> attribute, it indicates that setting the corresponding property
> on the platform object will result in that property being
> reconfigured to one that is unrelated to the attribute, and
> which has the value being assigned.

What happens if i delete a replacement for a replaceable property?
I believe the original property is exposed. The text should make this clear.

> Assigning to the value property on a platform object implementing
> Counter will sever the link between the property and the IDL
> attribute it initially corresponds to:

s/sever/disconnect|disable/ - severing is generally considered permanent.

Also, it'd be good to include an delete undoing this in the example.

Sorry, I ran out of time for today. I'll continue from 4.3.13.
[TreatNullAs] tomorrow.
Received on Wednesday, 13 July 2011 01:32:49 UTC

This archive was generated by hypermail 2.3.1 : Tuesday, 6 January 2015 21:37:45 UTC