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

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)
> <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 mdn/browser-compat-data#18910
> <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.
>
> —
> Reply to this email directly, view it on GitHub
> <https://github.com/w3c/webrtc-stats/issues/752#issuecomment-1496608030>,
> or unsubscribe
> <https://github.com/notifications/unsubscribe-auth/AAC5LEVZHB6G7TY4TRWKFFTW7SEVZANCNFSM6AAAAAAWRCIFAQ>
> .
> You are receiving this because you were mentioned.Message ID:
> ***@***.***>
>


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


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

Received on Wednesday, 5 April 2023 02:01:20 UTC