Comments on "API for Media Resource 1.0"

Hi,

A few comments based on a quick review of "API for Media Resource 1.0"
http://www.w3.org/TR/2009/WD-mediaont-api-1.0-20091020

Checking the WebIDL declaration using the WebIDL checker [1], I've found
the following bugs in the WebIDL: constant (in the exception
declarations) cannot take DOMString as types (only float, integers and
booleans).

(note that I had to copy & paste the IDL in the checker to verify it —
it would be great if the <pre> that encompasses the WebIDL declaration
could use a class="idl" which would make it possible for the checker to
detect it directly in the document itself)

But beyond purely syntactic considerations, the current proposed API
seem very awkward compared to most JavaScript APIs I know of; a few
examples of these awkwardnesses:
• using exceptions on every attribute declaration makes it really hard
to program (you need a try {} catch {} block each time you access the
said attribute); it would be much more natural to use nullable
attributes
http://dev.w3.org/2006/webapi/WebIDL/#idl-nullable-type
• given that you define a "Contributors" interface (which really should
be "Contributor"), why isn't MediaResource.contributors of the type
Contributors[] (rather than object[])? This applies to the other
attributes with the object and object[] types
• EcmaScript5 defines a Date object, which you really should consider
using instead of defining a new interface
• unless you expect structured data to be available for the location
attribute, I would suggest using a DOMString rather than a specific
object; if you really want a Location interface, the DAP and Geolocation
WGs have been working on one
• the duration of media resource should probably be expressed in
miliseconds rather than seconds (since second seem to lack the typical
kind of granularity one might be expecting at the programmatic level)

There is a pretty strong overlap between that work and some of the work
in the DAP Working Group (e.g. the Capture API, the possible Gallery
API), so I would suggest asking a review from the DAP Working Group much
earlier than at last call.

HTH,

Dom

1. http://www.w3.org/2009/07/webidl-check

Received on Thursday, 18 February 2010 15:58:57 UTC