Comments on API editors draft

Hi,

I've sent to the editors a pull request for a number of minor changes to
the Web IDL in the spec [0], but here are some other remarks that I
didn't know how to address trivially:

* the text uses must, may, should, and it seems like they are meant at
least sometimes in the RFC 2119 keywords; if so, I suggest they should
be marked up appropriately (ReSpec has a feature for that [4]), and RFC
2119 should be referenced accordingly

* PeerConnection uses numeric constants; there is an open bug on Web IDL
that proposes to rename "const" to "legacyconst" [1], and which reflects
the generally held opinion that numerical constants aren't a good design
for JavaScript APIs [5]; using string-based constants is usually
prefered (although the lack of an enum construct [2] makes it a bit
annoying to spec); on the case of MediaStream.readyState, since there
are only 2 values, maybe replacing by a boolean attribute would make
more sense

* MediaStreamEventInit has a bogus declaration for its only member:
"DOMstring MediaStream? stream" should be either "DOMstring stream" or
"MediaStream? stream"; more generally, I'm not quite sure what's the
intent of this optional argument is, nor how it would be used; maybe an
example would help?

* EventInit is defined in DOM4, so if we want to rely on that mechanism,
we should have a normative reference to it

* step 12 if the getUserMedia() algorithm says "if audio is true, then
the provided media should include an audio track"; this raises a few
issues:
 - the "should" should really apply to the user agent rather than to the
"provided media" (which can't do anything about it)
 - I think it should say "if audio is true and the user permits it, the
user agent should provide a media with an audio track" 
 - it would probably worth clarifying whether the user agent should
consider it a success if both video and audio are requested, but only
one of them is provided

* HTML5 defines AudioTrack, VideoTrack (and their *List equivalent);  it
sounds like Web RTC should reference them rather than create MediaTrack
(or we should start a discussion with the HTML WG if we think we need to
own or share it)

Dom

0 . most of the bugs I've spotted came from running the Web IDL checker
on the generated HTML from the API:
http://www.w3.org/2009/07/webidl-check
http://dev.w3.org/cvsweb/2009/webidl-checker/ (also runs as a command
line tool)
1. http://www.w3.org/Bugs/Public/show_bug.cgi?id=14878
2. http://www.w3.org/Bugs/Public/show_bug.cgi?id=11451
3. http://www.w3.org/TR/domcore/#eventinit
4. http://dev.w3.org/2009/dap/ReSpec.js/documentation.html#rfc-2119
5.
http://scriptlib-cg.github.com/api-design-cookbook/#don-t-use-numerical-constants

Received on Thursday, 24 November 2011 17:26:33 UTC