Merge pull request #1060 from Unity-Technologies/dw24-web-rtc

doc: Improve documentation of WebRTC

Author: miyabi

Runtime/Scripts/WebRTC.cs

@@ -631,8 +631,17 @@ public enum NativeLoggingSeverity
     };
 
     /// <summary>
-    ///
+    ///     Provides utilities and management functions for integrating WebRTC functionality. 
     /// </summary>
+    /// <remarks>
+    ///     `WebRTC` class provides a set of static methods and properties to manage the WebRTC functionality.
+    /// </remarks>
+    /// <example>
+    ///     <code lang="cs"><![CDATA[
+    ///         StartCoroutine(WebRTC.Update());
+    ///     ]]></code>
+    /// </example>
+    /// <seealso cref="WebRTCSettings"/>
     public static class WebRTC
     {
 #if UNITY_IOS
@@ -673,9 +682,17 @@ internal static void InitializeInternal(bool limitTextureSize = true, bool enabl
         }
 
         /// <summary>
-        ///
+        ///     Updates the texture data for all video tracks at the end of each frame.
         /// </summary>
-        /// <returns></returns>
+        /// <remarks>
+        ///    `Update` method updates the texture data for all video tracks at the end of each frame.
+        /// </remarks>
+        /// <returns>`IEnumerator` to facilitate coroutine execution.</returns>
+        /// <example>
+        ///     <code lang="cs"><![CDATA[
+        ///         StartCoroutine(WebRTC.Update());
+        ///     ]]></code>
+        /// </example>
         public static IEnumerator Update()
         {
             var instruction = new WaitForEndOfFrame();
@@ -715,15 +732,22 @@ public static IEnumerator Update()
         }
 
         /// <summary>
-        /// Executes any pending tasks generated asynchronously during the WebRTC runtime.
+        ///     Executes any pending tasks generated asynchronously during the WebRTC runtime.
         /// </summary>
+        /// <remarks>
+        ///     `ExecutePendingTasks` method processes pending tasks generated during WebRTC operations until reaching the specified timeout.
+        /// </remarks>
         /// <param name="millisecondTimeout">
-        /// The amount of time in milliseconds that the task queue can take before task execution will cease.
+        ///     The maximum time in milliseconds for which to process the task queue before task execution stops.
         /// </param>
         /// <returns>
-        /// <c>true</c> if all pending tasks were completed within <see cref="millisecondTimeout"/> milliseconds and <c>false</c>
-        /// otherwise.
+        ///     `true` if all pending tasks were completed within <see cref="millisecondTimeout"/> milliseconds and `false` otherwise.
         /// </returns>
+        /// <example>
+        ///     <code lang="cs"><![CDATA[
+        ///         WebRTC.ExecutePendingTasks(100);
+        ///     ]]></code>
+        /// </example>
         public static bool ExecutePendingTasks(int millisecondTimeout)
         {
             if (s_syncContext is ExecutableUnitySynchronizationContext executableContext)
@@ -735,7 +759,7 @@ public static bool ExecutePendingTasks(int millisecondTimeout)
         }
 
         /// <summary>
-        ///
+        ///     Controls whether texture size constraints are applied during WebRTC streaming.
         /// </summary>
         public static bool enableLimitTextureSize
         {
@@ -744,8 +768,8 @@ public static bool enableLimitTextureSize
         }
 
         /// <summary>
-        /// Get & set the logger to use when logging debug messages inside the WebRTC package.
-        /// By default will use Debug.unityLogger.
+        ///     Logger used for capturing debug messages within the WebRTC package.
+        ///     Defaults to Debug.unityLogger.
         /// </summary>
         /// <exception cref="ArgumentNullException">Throws if setting a null logger.</exception>
         public static ILogger Logger
@@ -766,10 +790,18 @@ public static ILogger Logger
         }
 
         /// <summary>
-        /// Configure native logging settings for WebRTC.
+        ///     Configures native logging settings for WebRTC.
         /// </summary>
+        /// <remarks>
+        ///     `ConfigureNativeLogging` method is used to enable or disable native logging and set the native logging level.
+        /// </remarks>
         /// <param name="enableNativeLogging">Enables or disable native logging.</param>
         /// <param name="nativeLoggingSeverity">Sets the native logging level.</param>
+        /// <example>
+        ///     <code lang="cs"><![CDATA[
+        ///         WebRTC.ConfigureNativeLogging(true, NativeLoggingSeverity.Warning);
+        ///     ]]></code>
+        /// </example>
         public static void ConfigureNativeLogging(bool enableNativeLogging, NativeLoggingSeverity nativeLoggingSeverity)
         {
             if (enableNativeLogging)
@@ -870,9 +902,18 @@ internal static RTCError ValidateTextureSize(int width, int height, RuntimePlatf
         }
 
         /// <summary>
-        ///
+        ///     Checks whether the specified graphics format is supported.
         /// </summary>
-        /// <param name="format"></param>
+        /// <remarks>
+        ///     `ValidateGraphicsFormat` method checks whether the provided `GraphicsFormat` is compatible with the current graphics device.
+        ///     This method throws an `ArgumentException` if the format is not supported.
+        /// </remarks>
+        /// <param name="format">`GraphicsFormat` value to be validated.</param>
+        /// <example>
+        ///     <code lang="cs"><![CDATA[
+        ///         WebRTC.ValidateGraphicsFormat(format);
+        ///     ]]></code>
+        /// </example>
         public static void ValidateGraphicsFormat(GraphicsFormat format)
         {
             // can't recognize legacy format
@@ -893,21 +934,40 @@ public static void ValidateGraphicsFormat(GraphicsFormat format)
         }
 
         /// <summary>
-        ///
+        ///     Determines the appropriate RenderTextureFormat for a given GraphicsDeviceType.
         /// </summary>
-        /// <param name="type"></param>
-        /// <returns></returns>
+        /// <remarks>
+        ///     `GetSupportedRenderTextureFormat` method determines the appropriate `RenderTextureFormat` for a given `GraphicsDeviceType`.
+        /// </remarks>
+        /// <param name="type">`GraphicsDeviceType` for which `RenderTextureFormat` is being determined.</param>
+        /// <returns>`RenderTextureFormat` value for the specified `GraphicsDeviceType`.</returns>
+        /// <example>
+        ///     <code lang="cs"><![CDATA[
+        ///         RenderTextureFormat format = WebRTC.GetSupportedRenderTextureFormat(GraphicsDeviceType.Direct3D11);
+        ///     ]]></code>
+        /// </example>
         public static RenderTextureFormat GetSupportedRenderTextureFormat(GraphicsDeviceType type)
         {
             var graphicsFormat = GetSupportedGraphicsFormat(type);
             return GraphicsFormatUtility.GetRenderTextureFormat(graphicsFormat);
         }
 
         /// <summary>
-        ///
+        ///     Determines the appropriate GraphicsFormat for a given GraphicsDeviceType.
         /// </summary>
-        /// <param name="type"></param>
-        /// <returns></returns>
+        /// <remarks>
+        ///     `GetSupportedGraphicsFormat` method determines the appropriate `GraphicsFormat` for a given `GraphicsDeviceType`.
+        /// </remarks>
+        /// <param name="type">`GraphicsDeviceType` for which `GraphicsFormat` is being determined.</param>
+        /// <returns>`GraphicsFormat` value for the specified `GraphicsDeviceType`.</returns>
+        /// <example>
+        ///     <code lang="cs"><![CDATA[
+        ///         int width = WebRTCSettings.StreamSize.x;
+        ///         int height = WebRTCSettings.StreamSize.y;
+        ///         GraphicsFormat format = WebRTC.GetSupportedGraphicsFormat(GraphicsDeviceType.Direct3D11);
+        ///         RenderTexture texture = new RenderTexture(width, height, 0, format);
+        ///     ]]></code>
+        /// </example>
         public static GraphicsFormat GetSupportedGraphicsFormat(GraphicsDeviceType type)
         {
             if (QualitySettings.activeColorSpace == ColorSpace.Linear)
@@ -947,10 +1007,18 @@ public static GraphicsFormat GetSupportedGraphicsFormat(GraphicsDeviceType type)
         }
 
         /// <summary>
-        ///
+        ///     Determines the appropriate TextureFormat for a given GraphicsDeviceType.
         /// </summary>
-        /// <param name="type"></param>
-        /// <returns></returns>
+        /// <remarks>
+        ///     `GetSupportedTextureFormat` method determines the appropriate `TextureFormat` for a given `GraphicsDeviceType`.
+        /// </remarks>
+        /// <param name="type">`GraphicsDeviceType` for which `TextureFormat` is being determined.</param>
+        /// <returns>`TextureFormat` value for the specified `GraphicsDeviceType`.</returns>
+        /// <example>
+        ///     <code lang="cs"><![CDATA[
+        ///         TextureFormat format = WebRTC.GetSupportedTextureFormat(GraphicsDeviceType.Direct3D11);
+        ///     ]]></code>
+        /// </example>
         public static TextureFormat GetSupportedTextureFormat(GraphicsDeviceType type)
         {
             var graphicsFormat = GetSupportedGraphicsFormat(type);