Inline RTCSessionDescriptionInit description (#33963)

* fix: Add missing documentation for RTCSessionDescriptionInit, RTCLocalSessionDescriptionInit Add missing documentation for RTCSessionDescriptionInit, RTCLocalSessionDescriptionInit interfaces. Also correct several links referencing those interfaces. Also add a clear explanation of the relationship between RTCSessionDescription, RTCSessionDescriptionInit, and RTCLocalSessionDescriptionInit interfaces. Fixes #33962 * Apply suggestions from code review Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * Apply Code Review Combine RTCSessionDescriptionInit and RTCLocalSessionDescriptionInit descriptions within the RTCSessionDescription page. Additionally, update any related links. * Update files/en-us/web/api/rtcsessiondescription/index.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * Update files/en-us/web/api/rtcsessiondescription/rtcsessiondescription/index.md * Update * Update files/en-us/web/api/rtcpeerconnection/setlocaldescription/index.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * Fix * Fix others --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Joshua Chen <[email protected]>
mdn · Oct 2, 2024 · 42f4039 · 42f4039
1 parent 7f42d89
commit 42f4039
Show file tree

Hide file tree

Showing 6 changed files with 73 additions and 110 deletions.
diff --git a/files/en-us/web/api/rtcpeerconnection/createanswer/index.md b/files/en-us/web/api/rtcpeerconnection/createanswer/index.md
@@ -52,7 +52,12 @@ The parameters for the older form of `createAnswer()` are described below, to ai
 
 ### Return value
 
-A {{jsxref("Promise")}} whose fulfillment handler is called with an object conforming to the {{domxref("RTCSessionDescriptionInit")}} dictionary which contains the SDP answer to be delivered to the other peer.
+A {{jsxref("Promise")}} that fulfills with an object containing the same properties as an {{domxref("RTCSessionDescription")}} objects:
+
+- `type`
+  - : A string whose value is `"answer"`.
+- `sdp`
+  - : A string containing the SDP describing the session, to be delivered to the remote peer.
 
 ## Examples
 

diff --git a/files/en-us/web/api/rtcpeerconnection/createoffer/index.md b/files/en-us/web/api/rtcpeerconnection/createoffer/index.md
@@ -12,8 +12,6 @@ The **`createOffer()`** method of the {{domxref("RTCPeerConnection")}} interface
 
 The SDP offer includes information about any {{domxref("MediaStreamTrack")}} objects already attached to the WebRTC session, codec, and options supported by the browser, and any candidates already gathered by the {{Glossary("ICE")}} agent, for the purpose of being sent over the signaling channel to a potential peer to request a connection or to update the configuration of an existing connection.
 
-The return value is a {{jsxref("Promise")}} which, when the offer has been created, is resolved with a [RTCSessionDescriptionInit](/en-US/docs/Web/API/RTCSessionDescription/RTCSessionDescription#options) dictionary containing the newly-created offer.
-
 ## Syntax
 
 ```js-nolint
@@ -57,8 +55,12 @@ The parameters for the older form of `createOffer()` are described below, to aid
 
 ### Return value
 
-A {{jsxref("Promise")}} whose fulfillment handler will receive an object conforming to the [RTCSessionDescriptionInit](/en-US/docs/Web/API/RTCSessionDescription/RTCSessionDescription#options) dictionary which contains the SDP describing the generated offer.
-That received offer should be delivered through the signaling server to a remote peer.
+A {{jsxref("Promise")}} that fulfills with an object containing the same properties as an {{domxref("RTCSessionDescription")}} objects:
+
+- `type`
+  - : A string whose value is `"offer"`.
+- `sdp`
+  - : A string containing the SDP describing the generated offer, to be delivered to the remote peer.
 
 ### Exceptions
 
@@ -99,7 +101,7 @@ myPeerConnection
   });
 ```
 
-In this code, the offer is created, and once successful, the local end of the {{domxref("RTCPeerConnection")}} is configured to match by passing the offer (which is represented using an object conforming to [RTCSessionDescriptionInit](/en-US/docs/Web/API/RTCSessionDescription/RTCSessionDescription#options)) into {{domxref("RTCPeerConnection.setLocalDescription", "setLocalDescription()")}}.
+In this code, the offer is created, and once successful, the local end of the {{domxref("RTCPeerConnection")}} is configured to match by passing the offer (which is represented using an object in the same shape as {{domxref("RTCSessionDescription")}}) into {{domxref("RTCPeerConnection.setLocalDescription", "setLocalDescription()")}}.
 Once that's done, the offer is sent to the remote system over the signaling channel; in this case, by using a custom function called `sendToServer()`.
 The implementation of the signaling server is independent from the WebRTC specification, so it doesn't matter how the offer is sent as long as both the caller and potential receiver are using the same one.
 

diff --git a/files/en-us/web/api/rtcpeerconnection/setlocaldescription/index.md b/files/en-us/web/api/rtcpeerconnection/setlocaldescription/index.md
@@ -28,47 +28,17 @@ setLocalDescription(sessionDescription, successCallback, errorCallback) // depre
 ### Parameters
 
 - `sessionDescription` {{optional_inline}}
-  - : An {{domxref("RTCSessionDescriptionInit")}} or {{domxref("RTCSessionDescription")}} which specifies the configuration to be applied to the local end of the connection.
-    If the description is omitted, the WebRTC runtime tries to automatically do the right thing.
-
-### Return value
 
-A {{jsxref("Promise")}} which is fulfilled once the value of {{domxref("RTCPeerConnection.localDescription")}} is successfully changed or rejected if the change cannot be applied (for example, if the specified description is incompatible with one or both of the peers on the connection).
-The promise's fulfillment handler receives no input parameters.
+  - : An object which specifies the configuration to be applied to the local end of the connection. It should contain the following properties:
 
-> [!NOTE]
-> The process of changing descriptions actually involves intermediary steps handled by the WebRTC layer to ensure that an active connection can be changed without losing the connection if the change does not succeed.
-> See [Pending and current descriptions](/en-US/docs/Web/API/WebRTC_API/Connectivity#pending_and_current_descriptions) in the WebRTC Connectivity page for more details on this process.
-
-#### Implicit description
-
-If you don't explicitly provide a session description, the WebRTC runtime will try to handle it correctly.
-If the signaling state is one of `stable`, `have-local-offer`, or `have-remote-pranswer`, the WebRTC runtime automatically creates a new offer and sets that as the new local description.
-Otherwise, `setLocalDescription()` creates an answer, which becomes the new local description.
-
-#### Type of the description parameter
-
-The description is of type `RTCSessionDescriptionInit`, which is a serialized version of a {{domxref("RTCSessionDescription")}} browser object. They're interchangeable:
-
-```js
-myPeerConnection
-  .createOffer()
-  .then((offer) => myPeerConnection.setLocalDescription(offer));
-```
+    - `type` {{optional_inline}}
+      - : A string indicating the type of the session description. If you don't explicitly provide a session description, the WebRTC runtime will try to handle it correctly. If the signaling state is one of `stable`, `have-local-offer`, or `have-remote-pranswer`, the WebRTC runtime automatically creates a new offer and sets that as the new local description. Otherwise, `setLocalDescription()` creates an answer, which becomes the new local description.
+    - `sdp` {{optional_inline}}
+      - : A string containing the SDP describing the session. If sdp is not provided, it defaults to an empty string. If `type` is `"rollback"`, `sdp` must be null or an empty string.
 
-This is equivalent to:
-
-```js
-myPeerConnection
-  .createOffer()
-  .then((offer) =>
-    myPeerConnection.setLocalDescription(new RTCSessionDescription(offer)),
-  );
-```
-
-For this reason, the {{domxref("RTCSessionDescription.RTCSessionDescription", "RTCSessionDescription()")}} constructor is deprecated.
+    If the description is omitted, the WebRTC runtime tries to automatically do the right thing.
 
-### Deprecated parameters
+    You can also pass an actual {{domxref("RTCSessionDescription")}} instance, but there's no difference. For this reason, the `RTCSessionDescription` constructor is deprecated.
 
 In older code and documentation, you may see a callback-based version of this function used.
 This has been deprecated and its use is **strongly** discouraged, as it will be removed in the future.
@@ -84,14 +54,23 @@ The parameters for the older form of `setLocalDescription()` are described below
 
 This deprecated form of the method returns instantaneously without waiting for the actual setting to be done: in case of success, the `successCallback` will be called; in case of failure, the `errorCallback` will be called.
 
+### Return value
+
+A {{jsxref("Promise")}} which is fulfilled once the value of {{domxref("RTCPeerConnection.localDescription")}} is successfully changed or rejected if the change cannot be applied (for example, if the specified description is incompatible with one or both of the peers on the connection).
+The promise's fulfillment handler receives no input parameters.
+
+> [!NOTE]
+> The process of changing descriptions actually involves intermediary steps handled by the WebRTC layer to ensure that an active connection can be changed without losing the connection if the change does not succeed.
+> See [Pending and current descriptions](/en-US/docs/Web/API/WebRTC_API/Connectivity#pending_and_current_descriptions) in the WebRTC Connectivity page for more details on this process.
+
 ### Deprecated exceptions
 
 When using the deprecated callback-based version of `setLocalDescription()`, the following exceptions may occur:
 
 - `InvalidStateError` {{domxref("DOMException")}} {{deprecated_inline}}
   - : Thrown if the connection's {{domxref("RTCPeerConnection.signalingState", "signalingState")}} is `"closed"`, indicating that the connection is not currently open, so negotiation cannot take place.
 - `InvalidSessionDescriptionError` {{domxref("DOMException")}} {{deprecated_inline}}
-  - : Thrown if the {{domxref("RTCSessionDescription")}} specified by the `sessionDescription` parameter is invalid.
+  - : Thrown if the `sessionDescription` parameter is invalid.
 
 ## Examples
 
@@ -141,3 +120,4 @@ called `signalRemotePeer()`.
 ## See also
 
 - [WebRTC API](/en-US/docs/Web/API/WebRTC_API)
+- {{domxref("RTCSessionDescription")}}
diff --git a/files/en-us/web/api/rtcpeerconnection/setremotedescription/index.md b/files/en-us/web/api/rtcpeerconnection/setremotedescription/index.md
@@ -23,37 +23,37 @@ Only then does the agreed-upon configuration take effect.
 
 ```js-nolint
 setRemoteDescription(sessionDescription)
+
+// deprecated
+setRemoteDescription(sessionDescription, successCallback, errorCallback)
 ```
 
 ### Parameters
 
 - `sessionDescription`
-  - : An {{domxref("RTCSessionDescriptionInit")}} or {{domxref("RTCSessionDescription")}} which specifies the remote peer's current offer or answer.
-    This value is an offer or answer received from the remote peer through your implementation of
 
-The `sessionDescription` parameter is technically of type `RTCSessionDescriptionInit`, but because {{domxref("RTCSessionDescription")}} serializes to be indistinguishable from `RTCSessionDescriptionInit`, you can also pass in an `RTCSessionDescription`.
-This lets you simplify code such as the following:
+  - : An object which specifies the remote peer's current offer or answer. It should contain the following properties:
 
-```js
-myPeerConnection
-  .setRemoteDescription(new RTCSessionDescription(description))
-  .then(() => createMyStream());
-```
+    - `type`
+      - : A string indicating the type of the session description. See {{domxref("RTCSessionDescription.type")}}.
+    - `sdp` {{optional_inline}}
+      - : A string containing the SDP describing the session. If sdp is not provided, it defaults to an empty string. If `type` is `"rollback"`, `sdp` must be null or an empty string. See {{domxref("RTCSessionDescription.sdp")}}.
 
-to be:
+    You can also pass an actual {{domxref("RTCSessionDescription")}} instance, but there's no difference. For this reason, the `RTCSessionDescription` constructor is deprecated.
 
-```js
-myPeerConnection.setRemoteDescription(description).then(() => createMyStream());
-```
-
-Using [`async`](/en-US/docs/Web/JavaScript/Reference/Statements/async_function)/[`await`](/en-US/docs/Web/JavaScript/Reference/Operators/await) syntax, you can further simplify this to:
+In older code and documentation, you may see a callback-based version of this function used.
+This has been deprecated and its use is _strongly_ discouraged.
+You should update any existing code to use the {{jsxref("Promise")}}-based version of `setRemoteDescription()` instead.
+The parameters for the older form of `setRemoteDescription()` are described below, to aid in updating existing code.
 
-```js
-await myPeerConnection.setRemoteDescription(description);
-createMyStream();
-```
+- `successCallback` {{deprecated_inline}}
+  - : A JavaScript {{jsxref("Function")}} which accepts no input parameters to be called once the description has been successfully set.
+    At that time, the offer can be sent to a remote peer via the signaling server.
+- `errorCallback` {{deprecated_inline}}
+  - : A function matching the signature `RTCPeerConnectionErrorCallback` which gets called if the description can't be set.
+    It is passed a single {{domxref("DOMException")}} object explaining why the request failed.
 
-Since it's unnecessary, the {{domxref("RTCSessionDescription.RTCSessionDescription", "RTCSessionDescription()")}} constructor is deprecated.
+This deprecated form of the method returns instantaneously without waiting for the actual setting to be done: in case of success, the `successCallback` will be called; in case of failure, the `errorCallback` will be called.
 
 ### Return value
 
@@ -80,7 +80,14 @@ The following exceptions are reported to the rejection handler for the promise r
   - : Returned with the {{domxref("RTCError.errorDetail", "errorDetail")}} set to `sdp-syntax-error` if the {{Glossary("SDP")}} specified by {{domxref("RTCSessionDescription.sdp")}} is not valid.
     The error object's {{domxref("RTCError.sdpLineNumber", "sdpLineNumber")}} property indicates the line number within the SDP on which the syntax error was detected.
 - {{jsxref("TypeError")}}
-  - : Returned if the specified `RTCSessionDescriptionInit` or `RTCSessionDescription` object is missing the {{domxref("RTCSessionDescription.type", "type")}} property, or no description parameter was provided at all.
+  - : Returned if the `sessionDescription` is missing the {{domxref("RTCSessionDescription.type", "type")}} property, or no description parameter was provided at all.
+
+When using the deprecated callback-based version of `setRemoteDescription()`, the following exceptions may occur:
+
+- `InvalidStateError` {{deprecated_inline}}
+  - : The connection's {{domxref("RTCPeerConnection.signalingState", "signalingState")}} is `"closed"`, indicating that the connection is not currently open, so negotiation cannot take place.
+- `InvalidSessionDescriptionError` {{deprecated_inline}}
+  - : The `sessionDescription` parameter is invalid.
 
 ## Usage notes
 
@@ -97,37 +104,6 @@ This happens instead of throwing an exception, thereby reducing the number of po
 > [!NOTE]
 > Earlier implementations of WebRTC would throw an exception if an offer was set outside a `stable` or `have-remote-offer` state.
 
-## Deprecated syntax
-
-In older code and documentation, you may see a callback-based version of this function used.
-This has been deprecated and its use is _strongly_ discouraged.
-You should update any existing code to use the {{jsxref("Promise")}}-based version of `setRemoteDescription()` instead.
-The parameters for the older form of `setRemoteDescription()` are described below, to aid in updating existing code.
-
-```js
-pc.setRemoteDescription(sessionDescription, successCallback, errorCallback);
-```
-
-### Parameters
-
-- `successCallback` {{deprecated_inline}}
-  - : A JavaScript {{jsxref("Function")}} which accepts no input parameters to be called once the description has been successfully set.
-    At that time, the offer can be sent to a remote peer via the signaling server.
-- `errorCallback` {{deprecated_inline}}
-  - : A function matching the signature `RTCPeerConnectionErrorCallback` which gets called if the description can't be set.
-    It is passed a single {{domxref("DOMException")}} object explaining why the request failed.
-
-This deprecated form of the method returns instantaneously without waiting for the actual setting to be done: in case of success, the `successCallback` will be called; in case of failure, the `errorCallback` will be called.
-
-### Exceptions
-
-When using the deprecated callback-based version of `setRemoteDescription()`, the following exceptions may occur:
-
-- `InvalidStateError` {{deprecated_inline}}
-  - : The connection's {{domxref("RTCPeerConnection.signalingState", "signalingState")}} is `"closed"`, indicating that the connection is not currently open, so negotiation cannot take place.
-- `InvalidSessionDescriptionError` {{deprecated_inline}}
-  - : The {{domxref("RTCSessionDescription")}} specified by the `sessionDescription` parameter is invalid.
-
 ## Examples
 
 Here we see a function which handles an offer received from the remote peer.
@@ -171,3 +147,4 @@ When our promise fulfillment handler is called, indicating that this has been do
 - {{domxref("RTCPeerConnection.remoteDescription")}},
   {{domxref("RTCPeerConnection.pendingRemoteDescription")}},
   {{domxref("RTCPeerConnection.currentRemoteDescription")}}
+- {{domxref("RTCSessionDescription")}}
diff --git a/files/en-us/web/api/rtcsessiondescription/index.md b/files/en-us/web/api/rtcsessiondescription/index.md
@@ -11,6 +11,11 @@ The **`RTCSessionDescription`** interface describes one end of a connection—or
 
 The process of negotiating a connection between two peers involves exchanging `RTCSessionDescription` objects back and forth, with each description suggesting one combination of connection configuration options that the sender of the description supports. Once the two peers agree upon a configuration for the connection, negotiation is complete.
 
+## Constructor
+
+- {{domxref("RTCSessionDescription.RTCSessionDescription", "RTCSessionDescription()")}} {{deprecated_inline}}
+  - : Creates a new `RTCSessionDescription` by specifying the `type` and `sdp`. All methods that accept `RTCSessionDescription` objects also accept objects with the same properties, so you can use a plain object instead of creating an `RTCSessionDescription` instance.
+
 ## Instance properties
 
 _The `RTCSessionDescription` interface doesn't inherit any properties._
@@ -24,8 +29,6 @@ _The `RTCSessionDescription` interface doesn't inherit any properties._
 
 _The `RTCSessionDescription` doesn't inherit any methods._
 
-- {{domxref("RTCSessionDescription.RTCSessionDescription", "RTCSessionDescription()")}} {{deprecated_inline}}
-  - : This constructor returns a new `RTCSessionDescription`. The parameter is a `RTCSessionDescriptionInit` dictionary containing the values to assign the two properties.
 - {{domxref("RTCSessionDescription.toJSON()")}}
   - : Returns a {{Glossary("JSON")}} description of the object. The values of both properties, {{domxref("RTCSessionDescription.type", "type")}} and {{domxref("RTCSessionDescription.sdp", "sdp")}}, are contained in the generated JSON.
 
@@ -36,7 +39,7 @@ signalingChannel.onmessage = (evt) => {
   if (!pc) start(false);
 
   const message = JSON.parse(evt.data);
-  if (message.sdp) {
+  if (message.type && message.sdp) {
     pc.setRemoteDescription(
       new RTCSessionDescription(message),
       () => {