Inline RTCSessionDescriptionInit description

[bc-lee]

Description

Add missing explanation of RTCSessionDescriptionInit and RTCLocalSessionDescriptionInit dictionaries. Also correct several links referencing those interfaces.

Motivation

Additional details

Related issues and pull requests

Fixes #33962

[skyclouds2001]

I think the two dictionaries are better not to placed in separate pages, as they both only contains two properties and both only used in one method

[Josh-Cena]

Hi! Unfortunately we don't document dictionaries on MDN, unless they are reused by a lot of methods (and even in such case we would usually just copy the property list around). Could you inline the description in the places where they are used instead?

[Josh-Cena]

We never mention the dictionary's name at all, because it's not a code entity. It should look like this:

  - : An object with the following properties:
    - `property1`
      - : What it does

And then for the errors, you would just say "the sessionDescription parameter is invalid".

[bc-lee]

Do you mean I should update the PR to remove any references to the directory name RTCSessionDescriptionInit? It existed before I submitted my PR.

[Josh-Cena]

Yes, they should be removed.

[bc-lee]

I'll keep my PR open for now, but I'm not sure if I can make any more changes, especially considering that the distinction of dictionary names is required since they are part of the WebRTC API. I believe it is important to retain the dictionary name in the documentation. If someone wants to take over the PR, I'm happy to close it.

[Josh-Cena]

Please see past changes where dictionaries were removed, for example #30080, #30079

[hamishwillee]

@bc-lee FYI @Josh-Cena is correct - the fact that the spec mentions these dictionaries is irrelevant. Specs are written for browser developers, while MDN interprets the specification for webapp developers.

In most cases we've found that having separate dictionaries is unhelpful for web app developers - they have to jump around to find relevant information, and often the compatibility data for the dictionary depends on where it is used. Because of that, the best way to properly track compatibility is to expand the dictionary.

We're not dogmatic about it. For some APIs it does actually make sense to define the objects passed to APIs as dictionaries. Generally this is when you have a general API that can take numerous possible objects depending on the context in which it is used.
This is not the case for WebRTC.

I haven't looked at this closely, but based on the comments we won't be merging this as is. I'm sure it will be useful though if modified to match MDN conventions.

[github-actions]

This pull request has merge conflicts that must be resolved before it can be merged.

[bc-lee]

Two days ago, a pull request relevant to this one (#34051) was merged. I'd like to hear from @Josh-Cena and @hamishwillee on whether you believe the merged PR achieves the same level of consistency as requested in this pull request.

[Josh-Cena]

@bc-lee I'm not sure what you want to express? That PR corrects incorrect information to correct information. While it doesn't remove documentation for dictionaries, that's fine because it's (a) making a correctness improvement, which is more important than editorial conventions (b) not adding more documentation pages for dictionaries.

Of course it would be better if that PR simply removed the mention to RTCSessionDescriptionInit altogether and just said "the return value is a promise resolved to an object with the following properties", but that's not necessary to qualify as a correctness PR. This PR on the other hand tries to introduce more documentation about a dictionary.

[Josh-Cena]

@bc-lee, do you have time to come back to this?

[bc-lee]

Yes, but not today or tomorrow (atm I'm busy with other things). I'll come back to this in a few days.

#33955 (comment)

[github-actions]

Preview URLs (6 pages)

• /en-US/docs/Web/API/RTCPeerConnection/createAnswer
• /en-US/docs/Web/API/RTCPeerConnection/createOffer
• /en-US/docs/Web/API/RTCPeerConnection/setLocalDescription
• /en-US/docs/Web/API/RTCPeerConnection/setRemoteDescription
• /en-US/docs/Web/API/RTCSessionDescription/RTCSessionDescription
• /en-US/docs/Web/API/RTCSessionDescription

(comment last updated: 2024-09-23 04:04:23)

[Josh-Cena]

I've simply inlined the descriptions in each page and reordered some sections. I did not do other major changes. Thanks for the PR!