Should we flatten the hierarchy?

[henbos]

Having non-observable WebIDL dictionaries that don't map to objects makes the spec less readable.

One argument for having them is not to have to define the same metric in multiple places like outbound-rtp + remote-outbound-rtp and inbound-rtp + remote-inbound-rtp. But saying the shared metrics are the same is not entirely accurate, as local metrics usually come from a local counter and remote metrics usually come from an RTCP packet, so it does make sense to have separate definitions for them.

Can we flatten so that "what you see (in the spec) is what you get"? One dictionary per JS observed object.

[henbos]

@alvestrand @vr000m @jan-ivar thoughts?

[henbos]

The hierarchy made a lot of sense when we had both "track" and "*-rtp" metrics, because then we truly had the same definitions in multiple places, but with the deprecation of "track", I think it s only a matter of time before these are moved to the provisional spec to reflect that they will have been unshipped (Chrome currently has a Deprecation Trial to remove "track" and "stream")

[jan-ivar]

Having non-observable WebIDL dictionaries that don't map to objects makes the spec less readable.

I don't think it's unreadable because of WebIDL inheritance, but because it's organized around dictionaries in the first place:

The above is dense and not very helpful to look things up.

As I mention in mdn/mdn#384 (comment) the better organization is https://w3c.github.io/webrtc-stats/#summary.

The lesson I draw from MDN here is that WebIDL dictionaries aren't APIs, they're details of an API. And if they're a detail, then whether they rely on inheritance or not should in theory also be a detail.

This seems obvious with method APIs like MDN's createDataChannel(label, options), which describes RTCDataChannelInit without mentioning its name (as part of the options input).

It's perhaps less obvious when the API is a maplike RTCStatsReport interface, but that's where MDN is moving stuff in mdn/browser-compat-data#18910, which I think is the right idea (for MDN at least).

I worry about changing the WebIDL inheritance, since that affects lexicographical order of members, a normative change requiring WG consensus.

I think editors should be able to improve the organization of the document a lot without resorting to that.

Step 1 might be to:

1. restructure the document itself to de-emphasize dictionaries, something like
   • Extensions to stats in RTCStatsReport
     • Breakdown by RTCStatsType:
       • "codec",
         • Introduce RTCCodecStats WebIDL here as a detail (without its own heading) to describe "codec"'s members
       • "inbound-rtp",
         • Introduce RTCInboundRtpStreamStats here as a detail, including its ancestors (ascending or descending list) if this is their first mention
       • "outbound-rtp",
         • Introduce RTCOutboundRtpStreamStats here as a detail
       • etc.

I.e. make the table of contents the RTCStatsTypes.

[vr000m]

I believe Jan-ivar’s suggestion was the original plan. We screwed up the indenting and we need to fix that. We may even have an issue that suggests what needs to be done. Let’s fix the sections/subsections first and return to flattening after that.

…

On Tue, Apr 4, 2023 at 17:08 Jan-Ivar Bruaroey ***@***.***> wrote: Having non-observable WebIDL dictionaries that don't map to objects makes the spec less readable. I don't think it's unreadable because of WebIDL inheritance, but because it's organized around dictionaries <https://w3c.github.io/webrtc-stats/#stats-dictionaries> in the first place: [image: image] <https://user-images.githubusercontent.com/3136226/229905578-cba93806-bbf2-40cc-be13-f480e3ea9a4c.png> The above is dense and not very helpful to look things up. As I mention in mdn/mdn#384 (comment) <mdn/mdn#384 (comment)> the better organization is https://w3c.github.io/webrtc-stats/#summary. The lesson I draw from MDN here is that WebIDL dictionaries aren't APIs, they're details of an API. And if they're a detail, then whether they rely on inheritance or not should in theory also be a detail. This seems obvious with method APIs like MDN's createDataChannel(label, options) <https://developer.mozilla.org/en-US/docs/Web/API/RTCPeerConnection/createDataChannel>, which describes RTCDataChannelInit <https://w3c.github.io/webrtc-pc/#dom-rtcdatachannelinit> without mentioning its name (as part of the options input). It's perhaps less obvious when the API is a maplike RTCStatsReport <https://w3c.github.io/webrtc-pc/#dom-rtcstatsreport> interface, but that's where MDN is moving stuff in mdn/browser-compat-data#18910 <mdn/browser-compat-data#18910>, which I think is the right idea (for MDN at least). I worry about changing the WebIDL inheritance, since that affects lexicographical order of members, a normative change requiring WG consensus. I think editors should be able to improve the organization of the document a lot without resorting to that. Step 1 might be to: 1. restructure the document itself to de-emphasize dictionaries, something like - Extensions to stats in RTCStatsReport <https://w3c.github.io/webrtc-pc/#dom-rtcstatsreport> - Breakdown by RTCStatsType <https://www.w3.org/TR/webrtc-stats/#dom-rtcstatstype>: - "codec <https://www.w3.org/TR/webrtc-stats/#dom-rtcstatstype-codec>", - Introduce RTCCodecStats WebIDL here as a detail (without its own heading) to describe "codec"'s members - "inbound-rtp <https://www.w3.org/TR/webrtc-stats/#dom-rtcstatstype-inbound-rtp>", - Introduce RTCInboundRtpStreamStats here as a detail, including its ancestors (ascending or descending list) if this is their first mention - "outbound-rtp <https://www.w3.org/TR/webrtc-stats/#dom-rtcstatstype-outbound-rtp>", - Introduce RTCOutboundRtpStreamStats here as a detail - etc. I.e. make the table of contents the RTCStatsTypes. — Reply to this email directly, view it on GitHub <#752 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAC5LEVZHB6G7TY4TRWKFFTW7SEVZANCNFSM6AAAAAAWRCIFAQ> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[henbos]

It's flatten enough :) let's close