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
detectable...

> 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

it.

> 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

“length”.
> 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].

s/4/6/

> 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

s/an/a/

>                               // 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/returned/retrieved/
s/Script/A script/

> platform object it was returned from.

s/returned/retrieved/

> 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

suggestion).

> 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

s/constrast/contrast/

> 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 : Wednesday, 8 May 2013 19:30:04 UTC