Re: WebIDL

Thanks for your responses. They are very useful. First of all, the
length of this response (and the explanations themselves) speak to the
difficulty casual spec readers have in understanding this syntax. More
specific responses inline.

On Fri, Sep 25, 2009 at 10:29 PM, Cameron McCormack <cam@mcc.id.au> wrote:
> 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.

So this extension effectively converts a readonly attribute to a
writable one? Talk about confusing. And this isn't true about the same
attribute in non-ES contexts?!

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

It wasn't clear from the text, but now that I understand it, it
doesn't help much. "An object that implements the interface on which a
read only attribute is defined will not allow assignment to that
attribute. It is language binding specific whether assignment is
simply disallowed by the language, ignored or an exception is thrown."
It's unclear to me how this is not specifying a requirement on the
language binding. This whole thing is extremely confusing.

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

If something is in WebIDL purely as a description for known legacy
behavior, it would be helpful if the case(s) in question were called
out in the spec, and use of the syntax was disallowed for other cases.

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

I'll put it another way: what's the utility of this additional word.
In my opinion, if a word appears in the HTML5 specification, it should
be there for a reason. If it is not, it just adds additional confusion
for readers of the spec.

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

So there's precedent then!

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

I think it buys clarity, but I'm not too concerned about it.

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

Well established and recognized by whom? I'd be more concerned with
newcomers than implementors (who will have no trouble adjusting to
small changes here).

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

I mean that nothing is *actually* present in onabort by default.

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

Which imposes a requirement on ECMAScript that such conversions be
defined and possible. This is not always (or even often) possible.

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

Understood. My confusion was answered by your response above, which is
where the spec specified coercions. Where does the spec specify how
Function should be coerced:

[Callback=FunctionOnly, NoInterfaceObject]
interface Function {
  any call(in any... arguments);
};

(at this point, a reasonable observer should be wondering how a reader
of the spec should be expected to figure any of this out)

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

Aha! And I was supposed to figure this out? Even if that information
was there, I would not have found it and put two and two together.

>
>> What does the type even mean in dynamic languages?
>
> Not sure what you mean here.  “Function” is an interface defined in
> HTML5.

[Callback=FunctionOnly, NoInterfaceObject]
interface Function {
  any call(in any... arguments);
};

Is this really something that you would expect a non-expert reader to
understand? Or is that just not a goal at all?

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

Ugh. From the spec: "However, the bindings in these specifications for
the language most commonly used on the web, ECMAScript, are
consistently specified with low enough precision as to result in
interoperability issues. In addition, each specification must describe
the same basic information, such as DOM interfaces described in IDL
corresponding to properties on the ECMAScript global object, or the
unsigned long IDL type mapping to the Number type in ECMAScript."

So it doesn't "map" but does "describe the same basic information".
I'm so confused :(

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

Again, I would ask which people it's familiar to. I think the people
for whom that statement is true are also the people with the least
need for special help understanding this stuff.

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

I'd be interested to know where in the spec these constructs are
described. I can't piece together how it's even valid WebIDL :/

>
>> 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). :-)

Touché!

>> 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?

The problem is that [Replaceable] readonly actually means "writeable
but only in ECMAScript", which is not something I even understood
before reading your reply. The right solution for that case would be,
as you expressed, to be explicit in WebIDL about the fact that this
extended property is a hack for known, specific legacy behavior.

>
>> Not quite an alternative proposal, but these are my thoughts.
>
> And thanks for them!
>
> Cameron
>
> --
> Cameron McCormack ≝ http://mcc.id.au/
>

Thanks for your time. Don't let my tone make you feel like you're
wasting your effort. I appreciate your attempts to explain things to
(noob) me.

-- 
Yehuda Katz
Developer | Engine Yard
(ph) 718.877.1325

Received on Saturday, 26 September 2009 06:07:11 UTC