doc: Improve documentation of RTCRtpTransceiver

Runtime/Scripts/RTCRtpTransceiver.cs

@@ -3,8 +3,23 @@
 namespace Unity.WebRTC
 {
     /// <summary>
-    /// 
+    ///     Describes a permanent pairing of an RTCRtpSender and an RTCRtpReceiver.
     /// </summary>
+    /// <remarks>
+    ///     `RTCRtpTransceiver` class is used to represent a permanent pairing of an `RTCRtpSender` and an `RTCRtpReceiver`, along with shared state.
+    /// </remarks>
+    /// <example>
+    ///     <code lang="cs"><![CDATA[
+    ///         RTCRtpCapabilities capabilities = RTCRtpSender.GetCapabilities(TrackKind.Video);
+    ///         RTCRtpTransceiver transceiver = peerConnection.GetTransceivers().First();
+    ///         RTCErrorType error = transceiver.SetCodecPreferences(capabilities.codecs);
+    ///         if (error.errorType != RTCErrorType.None)
+    ///         {
+    ///             Debug.LogError($"Failed to set codec preferences: {error.message}");
+    ///         }
+    ///     ]]></code>
+    /// </example>
+    /// <seealso cref="RTCPeerConnection"/>
     public class RTCRtpTransceiver : RefCountedObject
     {
         private RTCPeerConnection peer;
@@ -16,16 +31,27 @@ internal RTCRtpTransceiver(IntPtr ptr, RTCPeerConnection peer) : base(ptr)
         }
 
         /// <summary>
-        /// 
+        ///     Finalizer for RTCRtpTransceiver.
         /// </summary>
+        /// <remarks>
+        ///     Ensures that resources are released by calling the `Dispose` method
+        /// </remarks>
         ~RTCRtpTransceiver()
         {
             this.Dispose();
         }
 
         /// <summary>
-        /// 
+        ///     Disposes of RTCRtpTransceiver.
         /// </summary>
+        /// <remarks>
+        ///     `Dispose` method disposes of the `RTCRtpTransceiver` and releases the associated resources. 
+        /// </remarks>
+        /// <example>
+        ///     <code lang="cs"><![CDATA[
+        ///         transceiver.Dispose();
+        ///     ]]></code>
+        /// </example>
         public override void Dispose()
         {
             if (this.disposed)
@@ -40,7 +66,7 @@ public override void Dispose()
         }
 
         /// <summary>
-        /// 
+        ///     Specifies the negotiated media ID (mid) that uniquely identifies the pairing of the sender and receiver agreed upon by local and remote peers.
         /// </summary>
         public string Mid
         {
@@ -54,8 +80,7 @@ public string Mid
         }
 
         /// <summary>
-        /// This is used to set the transceiver's desired direction
-        /// and will be used in calls to CreateOffer and CreateAnswer.
+        ///     This is used to set the transceiver's desired direction and will be used in calls to CreateOffer and CreateAnswer.
         /// </summary>
         public RTCRtpTransceiverDirection Direction
         {
@@ -72,9 +97,9 @@ public RTCRtpTransceiverDirection Direction
         }
 
         /// <summary>
-        /// This property indicates the transceiver's current directionality,
-        /// or null if the transceiver is stopped or has never participated in an exchange of offers and answers.
-        /// To change the transceiver's directionality, set the value of the <see cref="Direction"/> property.
+        ///     This property indicates the transceiver's current directionality,
+        ///     or null if the transceiver is stopped or has never participated in an exchange of offers and answers.
+        ///     To change the transceiver's directionality, set the value of the Direction property.
         /// </summary>
         public RTCRtpTransceiverDirection? CurrentDirection
         {
@@ -90,7 +115,7 @@ public RTCRtpTransceiverDirection? CurrentDirection
         }
 
         /// <summary>
-        ///
+        ///     RTCRtpReceiver object that handles receiving and decoding incoming media data for the transceiver's stream.
         /// </summary>
         public RTCRtpReceiver Receiver
         {
@@ -102,7 +127,7 @@ public RTCRtpReceiver Receiver
         }
 
         /// <summary>
-        ///
+        ///     RTCRtpSender object that handles encoding and sending outgoing media data for the transceiver's stream.
         /// </summary>
         public RTCRtpSender Sender
         {
@@ -114,10 +139,31 @@ public RTCRtpSender Sender
         }
 
         /// <summary>
-        /// 
+        ///     Specifies the codecs for decoding received data on this transceiver, arranged in order of decreasing preference.
         /// </summary>
-        /// <param name="codecs"></param>
-        /// <returns></returns>
+        /// <remarks>
+        ///     `SetCodecPreferences` method sets codec preferences for negotiating data encoding with a remote peer.
+        ///     It requires reordering supported codecs by preference and applying them to influence the negotiation process.
+        ///     When initiating an `RTCPeerConnection`, set codecs before calling `CreateOffer` or `CreateAnswer`.
+        ///     Changing codecs during a session requires a new negotiation but does not automatically trigger the `OnNegotiationNeeded` event.
+        /// </remarks>
+        /// <param name="codecs">
+        ///     An array of `RTCRtpCodecCapability` objects arranged by preference to determine the codecs used for receiving and sending data streams.
+        ///     If it is empty, the codec configurations are all reset to the defaults.
+        /// </param>
+        /// <returns>`RTCErrorType` value.</returns>
+        /// <example>
+        ///     <code lang="cs"><![CDATA[
+        ///         RTCRtpCapabilities capabilities = RTCRtpSender.GetCapabilities(TrackKind.Video);
+        ///         RTCRtpTransceiver transceiver = peerConnection.GetTransceivers().First();
+        ///         RTCErrorType error = transceiver.SetCodecPreferences(capabilities.codecs);
+        ///         if (error.errorType != RTCErrorType.None)
+        ///         {
+        ///             Debug.LogError($"Failed to set codec preferences: {error.message}");
+        ///         }
+        ///     ]]></code>
+        /// </example>
+        /// <seealso cref="RTCPeerConnection"/>
         public RTCErrorType SetCodecPreferences(RTCRtpCodecCapability[] codecs)
         {
             RTCRtpCodecCapabilityInternal[] array = Array.ConvertAll(codecs, v => v.Cast());
@@ -132,9 +178,22 @@ public RTCErrorType SetCodecPreferences(RTCRtpCodecCapability[] codecs)
         }
 
         /// <summary>
-        /// 
+        ///     Stops the transceiver permanently by stopping both the associated RTCRtpSender and RTCRtpReceiver.
         /// </summary>
-        /// <returns></returns>
+        /// <remarks>
+        ///     Calling `Stop` method stops the sender from sending media immediately, closes RTP streams with an RTCP "BYE" message, and the receiver stops receiving media.
+        ///     The receiver's track ceases, and the transceiver's direction changes to `Stopped`.
+        /// </remarks>
+        /// <returns>`RTCErrorType` value.</returns>
+        /// <example>
+        ///     <code lang="cs"><![CDATA[
+        ///         RTCErrorType error = transceiver.Stop();
+        ///         if (error.errorType != RTCErrorType.None)
+        ///         {
+        ///             Debug.LogError($"Failed to stop transceiver: {error.message}");
+        ///         }
+        ///     ]]></code>
+        /// </example>
         public RTCErrorType Stop()
         {
             return NativeMethods.TransceiverStop(self);