WebIDL editorial feedback

http://dev.w3.org/2006/webapi/WebIDL/


> A scoped name .. is used in IDL to refer to definitions in different scopes.

s/different/other/ ?

> Let definition be the definition whose qualified name is equal to the concatenation of name, two U+003A COLON (":") characters and the scoped name, then the scoped name resolves to that definition; end these steps.

I found this statement to be strange, there's no "if", and no obvious
sign of what is being verified to decide whether to break. I'm sure we
all understand what the goal of the text is, but could the prose be
clarified?

>    // Exception field identifier: "code"
>    long code;

If something like this doesn't have a qualified name, then a comment
explaining it would be beneficial

>     If the definition is declared at the outermost scope, then the qualified name of the definition is two consecutive U+003A COLON (":") characters followed by the identifier of the definition.

> If the module has a [Prefix] extended attribute whose argument starts with the string “::”, then the prefixed name of the module is a scoped name constructed by concatenating the [Prefix] argument, the string “::” and the module’s identifier.

It seems like you'd be better served by defining a token to mean this
than using two different ways of expressing this content in the spec.

> Otherwise, if the module has a [Prefix] extended attribute whose argument does not start with the string “::”, then the prefixed name of the module is a scoped name constructed by concatenating the prefixed name of the module’s enclosing module (or “::” if there is no enclosing module), the string “::”, the [Prefix] argument, the string “::” and the module’s identifier.

I'm pretty sure this allows me to generate ::::foo::bar when there is
"no enclosing module", which seems wrong.

> module gfx {
> -blank line-
>  module geom {
>    interface Shape { /* ... */ }; -not-a-blank-line-
>    interface Rectangle : Shape { /* ... */ };
>    interface Path : Shape { /* ... */ };
>  }; -not-a-blank-line
> -blank-line
>  interface GraphicsContext {
>    void fillShape(in geom::Shape s);
>    void strokeShape(in geom::Shape s);
>  }; -not-a-blank-line-
> }; -not-a-blank-line-

I found the lack of a blank line before the lines i tagged as
"-not-a-blank-line-" made it hard to read the content, as I was
expecting a consistent and balanced whitespace style and this isn't.
(This also applies to the last line in module gui {...};)

> An interface is a definition (matching Interface) that defines an interface that objects in the system can implement.

"the system" seems odd.

> The scoped name MUST resolve to a a different interface.

s/a a/a/

> In addition, an implements statement can be used to define that objects implementing ane interface will always also implement another interface.

s/ane/an/

> All of the members that appear on the partial interface are considered to be members of the interface itself.

I presume there can be multiple partial interface statements for an
interface, in which case you probably want:

s/on the/on each of the/; s/partial interface/partial interfaces/

> The following IDL fragment demonstrates the definition of two mutually referential interfaces. Both Human and Dog inherit from Animal. Objects that implement either of those two interfaces will thus have a name attribute.
IDL

> interface Animal {
>   attribute DOMString name;
> };

> interface Human : Animal {
>   attribute Dog pet;
> };

s/Dog/Dog?/

> interface Dog : Animal {
>   attribute Human owner;
> };

s/Human/Human?/

The WebIDL spec used to imply null as a valid case, that changed.
Otherwise your mutually referential example is mostly unsolvable and
thus incredibly painful. Alternatively you could probably provide for
some other solution or a different example...

> U+0030 DIGIT ZERO ("0"), U+0058 LATIN CAPTIAL LETTER X ("X")

s/CAPTIAL/CAPITAL/

> [25] Get → InheritsGetter
>  | GetRaises
>  | ε
> [26] InheritsGetter → "inherits" "getter"
> [27] GetRaises → "getraises" ExceptionList
> [28] SetRaises → "setraises" ExceptionList
>  | ε

Is there a reason the ε is in Get instead of in GetRaises (to match SetRaises)?

> An argument MUST NOT be declared to be optional unless any subsequent arguments to the operation are also optional.

s/unless any/unless all/

> If an implementation attempts to invoke an operation on an object implemented by user code (for example, when a callback object has been supplied to the implementation), and that attempt results in an exception being thrown, then, unless otherwise specified, that exception will be propagated to the user code that caused the implementation to access the attribute.

s/access the attribute/invoke the operation/

> [39] Argument → ExtendedAttributeList In Optional Type Ellipsis identifier

It would be vaguely nice if if the syntax was described like this:

[x] ArgumentList → Argument Arguments VaradicArgument
 | ε
[x] Arguments → "," Argument Arguments
 | ε
[x] Argument → ExtendedAttributeList In Optional Type identifier

[x] VaradicArgument → ExtendedAttributeList In Optional Type "..." identifier
 | ε

(you could retain the "Ellipsis" token if you liked, but in that case
you should get rid of the | ε bit...)

> This approach is admitted to simplify prose descriptions of an interface’s operations.

s/admitted/allowed/ ?

> A given special keyword MUST NOT appear twice on an operation.

I don't understand the need for this. Doesn't the grammar prevent it
automatically?

> Special operations declared using operations MUST NOT be variadic nor have any optional arguments.

If you use the grammar I suggest above, you could probably adjust
other parts of the grammar to distinguish between ArgumentList and
PossiblyVaradicArgumentList....

> If an object implements more than one interface that defines a given special operation, then it is undefined which (if any) special operation is invoked.

s/invoked/invoked for that oepration/

> An ECMAScript implementation of the IDL would behave as follows:
> ECMAScript
>
> var s = new Student();

s/implementation of the/consumption of an object defined by that/ ? -
not a fan of consumption, please feel free to pick something else...

> interface OrderedMap {
>   readonly attribute unsigned long size;
...
> Objects implementing OrderedMap support indexed properties with indices in the range 0 ≤ index < OrderedMap::length.

s/length/size/ ?

I'll send comments about <3.3.4.4. Named properties> and further later.

Received on Friday, 8 July 2011 20:55:00 UTC