Re: WebIDL editorial feedback

> 3.3.4.4. Named properties

The section is called "Named properties", but many of the actual
things uses "name

<foo>" instead of "named <foo>".

I personally think of "foo[bar]" as a "named getter", because it's a
getter that gets

things for a named property, it does not "get the name of a thing".


If an interface supports named properties, then the interface
definition MUST be

accompanied by a description of what the ordered set of names the object can be

indexed with at any given time is.

s/what//; s/the object can be indexed with/that can index the object/; s/time

is/time/;

> Name getters and deleters MUST be declared to take a single DOMString argument.

s/Name/Named/ ?

> Index setters and creators MUST be declared to take two arguments, where the first

is an DOMString.

s/an DOMString/a DOMString/

---

I can't tell from the prose that only <name creator> and not <name setter> is

executed when doing a first assignment to foo[bar] for a "bar" not_in foo.

---

> A static operation is one that is not called on a particular instance of the

interface on which it is declared, and is instead associated with the interface

itself.

In Java, it's possible to do: ObjectInstance.staticFunction(args), which is

equivalent to Class.staticFunction(args). The prose above did not help
another reader

determine whether this was allowed here. In JavaScript, statics are
only available

from the Class and not the ObjectInstance.

---

> A dictionary can be defined to inherit from another dictionary.
> If the identifier of the dictionary is followed by a colon and a scoped name,
> then that scoped name identifies the inherited dictionary.
> The scoped name MUST resolve to a different dictionary.

> The inherited dictionaries of a given dictionary D is the set of
> all dictionaries that D inherits from, directly or indirectly.

There doesn't seem to be any propose here to prevent loops (there is in other

sections).

---

> [11] DictionaryMembers → ExtendedAttributeList DictionaryMember

DictionaryMembers
> | ε
> [12] DictionaryMember → Type identifier DefaultValue ";"

Is there a reason ExtendedAttributeList is in DictionaryMembers instead of in

DictionaryMember?

| [11] DictionaryMembers → DictionaryMember DictionaryMembers
| | ε
| [12] DictionaryMember → ExtendedAttributeList Type identifier

DefaultValue ";"

I guess it somewhat makes sense later for ExceptionMembers/ExceptionMember..

---

> In an ECMAScript implementation of the IDL,
> you an Object can be passed in for the optional PaintOptions dictionary:

s/you//

---

> No extended attributes are applicable to exception fields.

> [15] ExceptionMembers → ExtendedAttributeList ExceptionMember

ExceptionMembers

I think that you probably want to omit ExtendedAttributeList here, as the prose

forbids it...

---


> An exception can be defined to inherit from another exception.
> If the identifier of the exception is followed by a U+003A COLON (":")
> character and a scoped name, then that scoped name identifies the
> inherited exception. The scoped name MUST resolve to a different exception.

There doesn't seem to be any propose here to prevent loops (there is in other

sections).

> Each exception field (matching ExceptionField) is specified as a
> type (matching Type) followed by an identifier (given by an identifier
> token following the type). If the Type is a scoped name, then it MUST
> resolve to an interface or typedef.

Is there a reason 'interface' isn't linked? `resolve` is linked two paragraphs

earlier and again here.

---

> In an ECMAScript implementation, the different types of DOMExceptions
> could be distinguished in a number of different ways:
> ECMAScript

> } catch (e) {
>  // By testing with "instanceof".
>  if (e instanceof HierarchyRequestError) {

It would be good if you recommended that authors *never* use this method.

Some prose is probably valuable here:

"Note that using `instanceof <Exception>` can return `false` if the
exception object

comes from a different document than the global scope of the running
script even if

the exception is an instance of the an <Exception> class of the given
name in its own

document." -- Someone else can probably provide an improved block for
this, and see

thread [2] for comments about this hazard.

---

> A typedef is a definition (matching Typedef) used to declare a new name
> for a type. This new name is not exposed in language bindings;

s/in/by/

> it is purely used as a shorthand for referencing the type in the IDL.

---

> The type being given a new name is specified after the typedef keyword (matching

Type), and the identifier token following the type gives the name.
> The Type MUST NOT be a scoped name that resolves to an interface.

I think one of 'Type' or "NOT" here is wrong, I was reading:

> [16] Typedef → "typedef" Type identifier ";"

And assumed the 'NOT' was applying to 'Type', the prose probably wants:
s/Type/type/  -- to mean 'The type [being given the new name
`identifier`] MUST NOT

...', or
s/Type/identifier/.

---

> Implements statements can appear on a module or at the outermost scope.

s/on/in/

---

> 3.8. Objects implementing interfaces

> There is no way for a user object to represent an exception.

?

> Only interfaces with the following characteristics can be implemented as user

objects:

I found this list hard to parse, based on later prose, I think this should be

changed:

s/with/with all of/

Some additional prose might be warranted to remind readers that
<Dictionaries> are

also allowed....

Also note that "only...can" isn't an RFC word construct. It might be
better to say

something like "User objects SHOULD NOT be treated as an interface
unless all of the

following apply".

---

Afaict, this isn't forbidden or at least actively discouraged:

interface Foo {};
Foo implements Bar;
Foo implements Baz;
interface Bar { attribute short x; attribute short y; };
interface Baz { attribute short x; attribute short z; };

There is text in a couple of other sections which talks about things
being undefined

or needing to be clarified by prose, but there definitely isn't any near the

<implements> section.

---

> The interface and all of its inherited interface do not have any consequential

interfaces.

s/inherited interface/inherited interfaces/

> then the object will not be considered to be one that implements that interface.

s/will not/should not/

> This section lists the types supported by the IDL, the set of values each type

correspond to, and how constants of that type are represented.

s/the IDL/(Web|this|) IDL/
s/each type correspond to/corresponding to each type/

> all conversions necessary will be performed before the operation is invoked
> or the attribute updated.

s/will/should/ (RFC word)
s/updated/is updated/

> In some language bindings, type conversions could result in an exception being

thrown.

s/could/may/ ?

> In such cases, these exceptions will be propagated to the code that made the

attempt to invoke the operation or assign to the attribute.

s/will/should/ ?

There's actually text somewhere which talks about whether or not [3] this will

happen. Sometimes the exception might get swallowed. If I come across
the document

that talks about this, I'll reply with a note.

> [52] Type → AttributeType
> | "sequence" "<" Type ">" Null

I think it'd be good to have a SequenceType token.

> [60] TypeSuffixStartingWithArray → "[" "]" TypeSuffix
> | ε

I'm trying to understand the reason that TypeSuffixStartingWithArray exists in

WebIDL. It seems like its goal is to cause <AttributeType> for "any" to not be

nullable but to allow for arrays whose row and subs can be nulled.

> Note also that null is not a value of type DOMString. To allow null, a nullable

DOMString, written as DOMString? in IDL, can be used.

I know it's a note, but it feels like "must" or "should" would be
appropriate instead

of "can". You're trying to say "needs to be used"....

> Authors of specifications using Web IDL might want to obtain a sequence
> of Unicode characters given a particular sequence of 16 bit unsigned
> integer code units, however.

The "however" here feels dangling.

> There is no way to represent a sequence constant value in IDL.
> There is no way to represent an array constant value in IDL.
> There is no way to represent a Date constant value in IDL.

Should these be "constant <foo> value"?

> The instants in time that this type can represent are the same that can be
> represented with ECMAScript Date objects ([ECMA-262], section 15.9.1.1) –
> namely, every millisecond in the 200,000,000 days centered around midnight
> of 1 January, 1970 UTC, except for any millisecond that is part of an
> inserted leap seconds, which cannot be represented with this type.

s/seconds/second/
s/which cannot/because they cannot/; s/with this/by this/

> Any extended attribute encountered in an IDL fragment is matched
> against the following five grammar symbols to determine what form
> (or forms) it is in:

s/what/which/

> Although ExtendedAttributeIdent and ExtendedAttributeScopedName are
> ambiguous, no extended attribute defined in this document can take both
> of those forms.

s/can take/takes/

> It may be that [Callback] is not the best name for the extended attribute anyway,

although it does capture many uses of interfaces that user objects can
implement.

"UserObject" ?

> The [Callback] extended attribute MUST either take no argument or take an

identifier.

s/take no argument or take an identifier/take an identifier or no
argument/ -- it's

hard to parse the negation as currently written.

> Example
> The following IDL fragment defines simplified versions of
> a few DOM interfaces, one of which is annotated with the
> [Callback] extended attribute.

Please provide an example of [Callback(identifier)]. The prose is
insufficient for

this.

> Each ECMAScript global environment ([ECMA-262], section 10.2.3) MUST have
> its own unique set of each of the initial objects, created before control
> enters any ECMAScript execution context,

s/any/a related/

> but after the global object for that global environment is created. The
> [[Prototype]]s of all initial objects MUST come from

s/MUST/in a given global environment MUST/

> the same global environment.

You *might* want s/the/that/, it's a stronger restriction than the
current text --

currently a bunch of objects can all have prototypes which come from
one *other*

global environment (I've actually had code which did things like this,
but no one in

their right mind would want it -- thus my suggestion of s/the/that/).

> If the value is an object reference to a special object that represents
> an ECMAScript undefined value, then it is converted to the ECMAScript
> undefined value. Otherwise, the rules for converting the specific type
> of the IDL value are performed.

<the rules for converting the specific type of the IDL value> doesn't
seem to specify

something, is it a certain section? Is it the following list? ...

> ECMAScript functions that implement an operation whose IDL specifies a
> void return type MAY return any value, which will be discarded.

should `will` be SHOULD/MUST?

> Return the IDL boolean value is the one that represents the same truth

s/is/that is/

> value as the ECMAScript Boolean value x.

---

> Set x to x modulo 28.

Is modulo specifically meant to be an ECMAScript operation? If so, was there

something that indicidated that (if so, I missed it), if not, I think
you probably

need to specify whose modulo you're using (specifically relating to
how negative

numbers are handled).

I'll continue from 4.2.18. Nullable types — T? § tomorrow.

[2] http://lists.w3.org/Archives/Public/public-script-coord/2011JulSep/0014.html
[3] ?

Received on Monday, 11 July 2011 23:54:11 UTC