Re: WebIDL

Hi Yehuda.

Yehuda Katz:
> 1. There are a number of ECMAScript-specific extensions here that have
> obscure names and non-obvious behavior. For instance, understanding
> "[Replaceable] readonly" is non-trivial. In fact, "[Replaceable]
> readonly" has somewhat confusing semantics, in that the attribute is
> not really readonly at all. The readonly definition is "An object that
> implements the interface on which a read only attribute is defined
> will not allow assignment to that attribute", while [Replaceable]
> means "If the [Replaceable] extended attribute appears on a read only
> attribute, it indicates that setting the corresponding property on the
> host object will result in that property being removed and a new one
> created that is unrelated to the attribute, and which has the value
> being assigned".
> 
> In fact, aren't these properties not readonly at all. Instead, doesn't
> this idiom mean that the property is linked to some invisible
> attribute that is also used by other methods? Isn't that a more useful
> thing to express?

In the ES binding, the properties for these [Replaceable] attributes are
effectively writable, but assigning to them breaks their link to the
original attribute.  The assignment doesn’t perform any conversion from
the ES value to the IDL type, either.  In other language bindings you
would want these properties to behave like normal readonly attributes,
e.g. in Java by having only a setter method.

Note that, while it may not be clear from the text, section 3 of Web IDL
only makes requirements of IDL fragments, not on language bindings for
any interfaces.  The talk about not allowing assignment to the attribute
is a true description of both the ES and the Java bindings: the IDL
attribute itself isn’t writable, but [Replaceable] indicates that the ES
property that reflects that attribute is writable (and does something
non-obvious).

I wonder if for [Replaceable] and other similar hacks for legacy DOM
behaviour we should state that they SHOULD NOT be used.

> 2. Can't we have more useful defaults here? For instance, why can't
> 
> >  readonly attribute WindowProxy parent;
> >  readonly attribute Element frameElement;
> >  WindowProxy open(in optional DOMString url, in optional DOMString target, in optional DOMString features, in optional DOMString replace);
> 
> be identical to
> 
> >  readonly WindowProxy parent;
> >  readonly Element frameElement;
> >  WindowProxy open(optional DOMString url, optional DOMString target, optional DOMString features, optional DOMString replace);

We could make the syntax for attributes less similar to OMG IDL’s by
dropping the “attribute” keyword, but given that people are familiar
with this syntax (pre-Web IDL) and that implementations use IDL files
with this syntax as part of their builds, I’m not sure it’s worth it.

Although, we did drop the requirement for the “in” keyword:

  The "in" keyword used in the declaration of each argument is optional.
  No other types of arguments (such as out or in-out arguments) can be
  specified with Web IDL. 
   — http://dev.w3.org/2006/webapi/WebIDL/#idl-operations

> Additionally, isn't this stream of characters somewhat confusing? What about:
> 
> >  readonly parent: returns WindowProxy;
> >  readonly frameElement: returns Element;
> >  open(optional DOMString url, optional DOMString target, optional DOMString features, optional DOMString replace): returns WindowProxy;

Similarly, I don’t think moving the return type to the end buys us
anything.

> The specifics here aren't so important. My question is around
> whether some well-selected defaults (like "in" for arguments) might
> significantly reduce the amount of necessary verbiage.

I agree with the principle, but some of the basics of the IDL syntax are
well established and recognised.  (It probably argues against the use of
“returns” in your example above, too.)

> 3. In the case of events, there's a bit of fudging going on, isn't
> there? There is no default type,

I’m not sure what you mean by default type here.

> and nothing forces the user to provide a Function.

Right, the author could assign anything.  But the rules for how to
handle arbitrary ES values are defined:

  If a host object implements an interface, then for each attribute
  defined on the interface, there MUST be a corresponding property on
  the host object: 
    ...
    * If the attribute is not declared readonly, then when setting the
      property to a particular ECMAScript value, the IDL value assigned
      to the attribute is the result of converting the ECMAScript value
      to an IDL value. 
   — http://dev.w3.org/2006/webapi/WebIDL/#host-objects

> When looking at WebIDL, attribute types are defined thusly:
> 
> > The type of the attribute is given by the DeclarationType
> > non-terminal. If the DeclarationType is a scoped name, then it must
> > resolve, with respect to the enclosing module of the interface on
> > which the attribute is defined, to an interface, typedef or boxed
> > valuetype that has been declared previously.
> 
> There's no clear description of what that actually *means*.

It’s a requirement on IDL fragments.  It means that

  interface A {
    attribute B x;
  };

  interface B { };

is not conforming while

  interface B { };

  interface A {
    attribute B x;
  };

is.  There have been discussions on removing this requirement, though.

> Should implementors reject an attempt to assign a different type to
> the attribute? By what mechanism? 

In the ES binding, you need to follow the rules for converting the ES
value to an IDL value according to section 4.1 (that’s where the
“converting” word is linked to, in the text I quoted above).  Function
is an interface type, so the rules in 4.1.15 should apply:

  http://dev.w3.org/2006/webapi/WebIDL/#es-interface

That section should say something about handling [Callback]-annotated
interfaces, but it doesn’t seem to.  The intention is for the rules in
4.2.2 to apply:

  http://dev.w3.org/2006/webapi/WebIDL/#Callback
  
> What does the type even mean in dynamic languages?

Not sure what you mean here.  “Function” is an interface defined in
HTML5.

> 4. There are some cases where WebIDL requires the use of a type that
> is effectively mapped to ECMAScript types. For instance, instead of
> requiring the use of "unsigned long", why not simply define "Number"
> and use that? This would make it easier for casual readers of the
> spec.

unsigned long doesn’t map exactly to Number.  Assigning a Number to an
unsigned long attribute does truncation, for example:

  http://dev.w3.org/2006/webapi/WebIDL/#es-unsigned-long
  
The case could be made for “float”, which maps to Number (apart from
floats being exactly IEEE 754 singles whereas Number treats all NaNs the
same).  The type name “float” comes from OMG IDL and is thus already
familiar to people.  I think it’s a better name for that IDL type (i.e.,
language binding neutral type) than Number.

> 5. There are some things I can't make heads or tails of, like:
> 
> >  getter WindowProxy (in unsigned long index);
> >  getter WindowProxy (in DOMString name);

I think Boris explained those correctly.

> 6. In a previous thread, the WebIDL spec was called "short". I printed
> out the spec to PDF to test that, and it ran 78 pages. That may well
> be considered "short" in the realm of standards bodies, but it's a
> rather heavy requirement for reading a spec like HTML5.

Hey, it’s well within the range of a short (≤ 32767 pages). :-)

> Additionally, it's not a very simple spec to understand. Putting
> together things like "[Replaceable] readonly" requires some conceptual
> work, which makes understanding the HTML5 spec quite difficult.

I agree that’s unintuitive.  Would a different name for the extended
attribute here help?

> Not quite an alternative proposal, but these are my thoughts.

And thanks for them!

Cameron

-- 
Cameron McCormack ≝ http://mcc.id.au/

Received on Saturday, 26 September 2009 05:30:24 UTC