content
content copied to clipboard
mdn
fix: Add missing documentation for RTCSessionDescriptionInit, RTCLocalSessionDescriptionInit
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
Do you mean I should update the PR to remove any references to the directory name RTCSessionDescriptionInit? It existed before I submitted my PR.
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.
Please see past changes where dictionaries were removed, for example https://github.com/mdn/content/pull/30080, https://github.com/mdn/content/pull/30079
@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.
This pull request has merge conflicts that must be resolved before it can be merged.
![github-actions[bot] avatar](https://avatars.githubusercontent.com/in/15368?v=4 "Published by a pub.dev verified publisher"){kind=small}
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.
@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.
Yes, but not today or tomorrow (atm I'm busy with other things). I'll come back to this in a few days.
https://github.com/mdn/content/pull/33955#issuecomment-2284985438
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)