Re: Stats interface - possible change in WebIDL documentation format

On 05/15/2013 02:29 PM, Jim Barnett wrote:
>
> What is the relationship between the id attribute of the RTCStats 
> interface and the id argument passed to the getter?  It seems 
> confusing to me to have an object with an ‘id’ attribute and then a 
> getter method that takes some other id.
>
They are the same (the only valid reason to use the same name).

> -Jim
>
> *From:*Harald Alvestrand [mailto:harald@alvestrand.no]
> *Sent:* Wednesday, May 15, 2013 7:59 AM
> *To:* public-webrtc@w3.org
> *Subject:* Stats interface - possible change in WebIDL documentation 
> format
>
> (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;
>     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.
>
> 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)?
>
>           Harald
>