Re: Stats interface - possible change in WebIDL documentation format

On 5/15/13 7:59 AM, Harald Alvestrand wrote:
> (Theory-laden subject ahead... this should affect our WebIDL, but not 
> our Javascript. People who only care about the Javascript can skip this.)
>
> In an unrelated discussion this month, I learned something I hadn't 
> really considered before:
>
> In a dictionary, all members are by definition optional.
>
> This affects the stats interface specification. Currently we have:
>
> interface RTCStatsReport {
>     getter RTCStats (DOMString id);
> };
>
> dictionary RTCStats {
>     DOMHiResTimeStamp timestamp;

Is this a spec typo (Hi vs High)? Don't we mean DOMHighResTimeStamp from 
http://www.w3.org/TR/hr-time/#domhighrestimestamp ?

More comments below.

>     RTCStatsType      type;
>     DOMString         id;
> };
>
> And then all the other RTCStats objects are defined as subtypes of 
> this dictionary.
>
> But - timestamp, type and id are NOT intended to be optional. Thus, 
> the IDL does not provide the maximum amount of information to the user.

I don't think dictionaries are as much of a problem for "guaranteed 
args" in output to a client as it is for "required args" in input from a 
client to an API, because with input, the requirement is on the client 
(and required args must be expressed well in an API or clients will get 
it wrong), whereas with output the requirement is on the user agent (the 
browser), and browsers are required to read prose. :-)

Since in RTCStatsReport, dictionaries are used to return info from a 
browser to a client, I think the requirement on the user agent is better 
expressed in prose that says "the user client MUST return timestamp, 
type and id", without complicating the API.

If a client misses this in the spec, then the worst that happens is that 
they do extra checking on returned args that they didn't need to do.

> One suggested approach, keeping the dictionaries for the rest of the 
> stuff, would be:
>
> interface RTCStats {
>     DOMHiResTimeStamp timestamp;
>     RTCStatsType      type;
>     DOMString         id;
>     getter Any(DOMString id);
> }
>
> // Empty dictionary to serve as the base for further dictionaries
> dictionary RTCStatsBase {
> }
>
>
> with the comment "The id argument to the RTCStats getter is 
> constrained to be a valid member of the RTCStatsBase dictionary or a 
> subtype thereof".
>
> Question to the group:
>
> - Does anyone care?
> - Does the proposed solution make sense (both as WebIDL and as 
> documentation)?

I think it makes sense, but I hope we wont do this, because I think the 
extra API complication isn't worth the problem it solves, and you still 
end up with a comment (for the new id wart) - If we're going to have a 
comment, I'd prefer "timestamp, type and id are guaranteed" and go with 
the original API, as I found it clearer.

Also, (and this is a webidl technical issue, so I apologize to the 
larger group) a disadvantage with what you propose is that since getters 
have name collision issues (meaning RTCStats["type"] will resolve to the 
inherent property unless [OverrideBuiltins] is specified, which is fine 
because that's what you want), this prevents us from ever using 
[OverrideBuiltins] to protect the api against other mistakes like 
RTCStats["toString"]. A minor point.

Lastly, I'm sure there will be other args that are guaranteed for 
specific queries, and this proposal only solves timestamp, type and id, 
so a very small win IMHO.

>           Harald

.: Jan-Ivar :.