Re: [webrtc-stats] Should we flatten the hierarchy? (#752)

> 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:

<img width="768" alt="image" src="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 https://github.com/mdn/mdn/issues/384#issuecomment-1492646572 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 https://github.com/mdn/browser-compat-data/pull/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.


-- 
GitHub Notification of comment by jan-ivar
Please view or discuss this issue at https://github.com/w3c/webrtc-stats/issues/752#issuecomment-1496608030 using your GitHub account


-- 
Sent via github-notify-ml as configured in https://github.com/w3c/github-notify-ml-config

Received on Tuesday, 4 April 2023 21:08:36 UTC