Re: Comments on API editors draft

Thanks Dom!

I'm sure the editors will attack those issues when they wake up from the 
Thanksgiving weekend; is it possible / easy to set up procedures that 
make sure we run the WebIDL checker on every checkin of the edited document?

                Harald


On 11/24/2011 06:26 PM, Dominique Hazael-Massieux wrote:
> 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 Friday, 25 November 2011 13:35:30 UTC