WebIDL

At the urging of some folks, I've poked around WebIDL and have a few
observations. I'll use the Window object from HTML as a prop here (it
is reproduced, in full, below):

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?

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

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;

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.

3. In the case of events, there's a bit of fudging going on, isn't
there? There is no default type, and nothing forces the user to
provide a Function. 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*. Should
implementors reject an attempt to assign a different type to the
attribute? By what mechanism? What does the type even mean in dynamic
languages?

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.

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

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

---

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

---

[OverrideBuiltins]
interface Window {
  // the current browsing context
  readonly attribute WindowProxy window;
  readonly attribute WindowProxy self;
           attribute DOMString name;
  [PutForwards=href] readonly attribute Location location;
  readonly attribute History history;
  readonly attribute UndoManager undoManager;
  Selection getSelection();
  [Replaceable] readonly attribute BarProp locationbar;
  [Replaceable] readonly attribute BarProp menubar;
  [Replaceable] readonly attribute BarProp personalbar;
  [Replaceable] readonly attribute BarProp scrollbars;
  [Replaceable] readonly attribute BarProp statusbar;
  [Replaceable] readonly attribute BarProp toolbar;
  void close();
  void focus();
  void blur();

  // other browsing contexts
  [Replaceable] readonly attribute WindowProxy frames;
  [Replaceable] readonly attribute unsigned long length;
  readonly attribute WindowProxy top;
  [Replaceable] readonly attribute WindowProxy opener;
  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);
  getter WindowProxy (in unsigned long index);
  getter WindowProxy (in DOMString name);

  // the user agent
  readonly attribute Navigator navigator;
  readonly attribute ApplicationCache applicationCache;

  // user prompts
  void alert(in DOMString message);
  boolean confirm(in DOMString message);
  DOMString prompt(in DOMString message, in optional DOMString default);
  void print();
  any showModalDialog(in DOMString url, in optional any argument);

  // cross-document messaging
  void postMessage(in any message, in DOMString targetOrigin);
  void postMessage(in any message, in MessagePortArray ports, in
DOMString targetOrigin);

  // event handler IDL attributes
           attribute Function onabort;
           attribute Function onafterprint;
           attribute Function onbeforeprint;
           attribute Function onbeforeunload;
           attribute Function onblur;
           attribute Function oncanplay;
           attribute Function oncanplaythrough;
           attribute Function onchange;
           attribute Function onclick;
           attribute Function oncontextmenu;
           attribute Function ondblclick;
           attribute Function ondrag;
           attribute Function ondragend;
           attribute Function ondragenter;
           attribute Function ondragleave;
           attribute Function ondragover;
           attribute Function ondragstart;
           attribute Function ondrop;
           attribute Function ondurationchange;
           attribute Function onemptied;
           attribute Function onended;
           attribute Function onerror;
           attribute Function onfocus;
           attribute Function onformchange;
           attribute Function onforminput;
           attribute Function onhashchange;
           attribute Function oninput;
           attribute Function oninvalid;
           attribute Function onkeydown;
           attribute Function onkeypress;
           attribute Function onkeyup;
           attribute Function onload;
           attribute Function onloadeddata;
           attribute Function onloadedmetadata;
           attribute Function onloadstart;
           attribute Function onmessage;
           attribute Function onmousedown;
           attribute Function onmousemove;
           attribute Function onmouseout;
           attribute Function onmouseover;
           attribute Function onmouseup;
           attribute Function onmousewheel;
           attribute Function onoffline;
           attribute Function ononline;
           attribute Function onpause;
           attribute Function onplay;
           attribute Function onplaying;
           attribute Function onpopstate;
           attribute Function onprogress;
           attribute Function onratechange;
           attribute Function onreadystatechange;
           attribute Function onredo;
           attribute Function onresize;
           attribute Function onscroll;
           attribute Function onseeked;
           attribute Function onseeking;
           attribute Function onselect;
           attribute Function onshow;
           attribute Function onstalled;
           attribute Function onstorage;
           attribute Function onsubmit;
           attribute Function onsuspend;
           attribute Function ontimeupdate;
           attribute Function onundo;
           attribute Function onunload;
           attribute Function onvolumechange;
           attribute Function onwaiting;
};
Window implements EventTarget;


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

Received on Saturday, 26 September 2009 02:56:06 UTC