[NUI.Gadget] Enhance API descriptions (#6375)

Signed-off-by: Hwankyu Jhun <[email protected]>

src/Tizen.NUI.Gadget/Tizen.NUI/NUIGadget.cs

@@ -22,16 +22,25 @@
 namespace Tizen.NUI
 {
     /// <summary>
-    /// This class represents a NUIGadget controlled lifecycles.
+    /// Represents a NUIGadget controlled lifecycle.
     /// </summary>
+    /// <remarks>
+    /// This class provides functionality related to managing the lifecycle of a NUIGadget.
+    /// It enables developers to handle events such as initialization, activation, deactivation, and destruction of the gadget.
+    /// By implementing this class, developers can define their own behavior for these events and customize the lifecycle of their gadgets accordingly.
+    /// </remarks>
     /// <since_tizen> 10 </since_tizen>
     [EditorBrowsable(EditorBrowsableState.Never)]
     public abstract class NUIGadget
     {
         /// <summary>
         /// Initializes the gadget.
         /// </summary>
-        /// /// <param name="type">The type of the NUIGadget.</param>
+        /// <param name="type">The type of the NUIGadget.</param>
+        /// <remarks>
+        /// This constructor initializes a new instance of the NUIGadget class based on the specified type.
+        /// It is important to provide the correct type argument in order to ensure proper functionality and compatibility with other components.
+        /// </remarks>
         /// <since_tizen> 10 </since_tizen>
         public NUIGadget(NUIGadgetType type)
         {
@@ -44,7 +53,11 @@ public NUIGadget(NUIGadgetType type)
         /// <summary>
         /// Gets the class representing information of the current gadget.
         /// </summary>
-        /// <remarks> This property is set before the OnCreate() is called, after the instance has been created. </remarks>
+        /// <remarks>
+        /// This property is set before the OnCreate() is called, after the instance has been created.
+        /// It provides details about the current gadget such as its ID, name, version, and other relevant information.
+        /// By accessing this property, developers can retrieve the necessary information about the gadget they are working on.
+        /// </remarks>
         /// <since_tizen> 10 </since_tizen>
         public NUIGadgetInfo NUIGadgetInfo
         {
@@ -53,7 +66,7 @@ public NUIGadgetInfo NUIGadgetInfo
         }
 
         /// <summary>
-        /// Gets the type.
+        /// Gets the type of the NUI gadget.
         /// </summary>
         /// <since_tizen> 10 </since_tizen>
         public NUIGadgetType Type
@@ -65,7 +78,10 @@ public NUIGadgetType Type
         /// <summary>
         /// Gets the class name.
         /// </summary>
-        /// <remarks> This property is set before the OnCreate() is called, after the instance has been created. </remarks>
+        /// <remarks>
+        /// This property is set before the OnCreate() is called, after the instance has been created.
+        /// It provides access to the name of the class that was used to create the current instance.
+        /// </remarks>
         /// <since_tizen> 10 </since_tizen>
         public string ClassName
         {
@@ -74,7 +90,7 @@ public string ClassName
         }
 
         /// <summary>
-        /// Gets the main view.
+        /// Gets the main view of the NUI gadget..
         /// </summary>
         /// <since_tizen> 10 </since_tizen>
         public View MainView
@@ -84,7 +100,7 @@ public View MainView
         }
 
         /// <summary>
-        /// Gets the lifecycle state.
+        /// Gets the current lifecycle state of the gadget.
         /// </summary>
         /// <since_tizen> 10 </since_tizen>
         public NUIGadgetLifecycleState State
@@ -96,7 +112,11 @@ public NUIGadgetLifecycleState State
         /// <summary>
         /// Gets the resource manager.
         /// </summary>
-        /// <remarks> This property is set before the OnCreate() is called, after the instance has been created. </remarks>
+        /// <remarks> This property is set before the OnCreate() is called, after the instance has been created.
+        /// It provides access to various resources such as images, sounds, and fonts that can be used in your application.
+        /// By utilizing the resource manager, you can easily manage and retrieve these resources without having to manually handle their loading and unloading.
+        /// Additionally, the resource manager ensures efficient memory management by automatically handling the caching and recycling of resources.
+        /// </remarks>
         /// <since_tizen> 10 </since_tizen>
         public NUIGadgetResourceManager NUIGadgetResourceManager
         {
@@ -172,8 +192,8 @@ private void NotifyLifecycleChanged()
         }
 
         /// <summary>
-        /// Overrides this method if want to handle behavior when the gedget is started.
-        /// If 'base.OnCreate()' is not called, the event 'NUIGadgetLifecycleChanged' with  the 'NUIGadgetLifecycleState.Created' state will not be emitted.
+        /// Override this method to define the behavior when the gadget is created.
+        /// Calling 'base.OnCreate()' is necessary in order to emit the 'NUIGadgetLifecycleChanged' event with the 'NUIGadgetLifecycleState.Created' state.
         /// </summary>
         /// <returns>The main view object.</returns>
         /// <since_tizen> 10 </since_tizen>
@@ -187,15 +207,19 @@ protected virtual Tizen.NUI.BaseComponents.View OnCreate()
         /// <summary>
         /// Overrides this method if want to handle behavior when the gadget receives the appcontrol message.
         /// </summary>
-        /// <param name="e">The appcontrol received event argument.</param>
+        /// <remarks>
+        /// This method provides a way to customize the response when the gadget receives an appcontrol message.
+        /// By overriding this method in your derived class, you can define specific actions based on the incoming arguments.
+        /// </remarks>
+        /// <param name="e">The appcontrol received event argument containing details about the received message.</param>
         /// <since_tizen> 10 </since_tizen>
         protected virtual void OnAppControlReceived(AppControlReceivedEventArgs e)
         {
         }
 
         /// <summary>
-        /// Overrides this method if want to handle behavior when the gadget is destroyed.
-        /// If 'base.OnDestroy()' is not called. the event 'NUIGadgetLifecycleChanged' with the 'NUIGadgetLifecycleState.Destroyed' state will not be emitted.
+        /// Override this method to handle the behavior when the gadget is destroyed.
+        /// If 'base.OnDestroy()' is not called, the 'NUIGadgetLifecycleChanged' event with the 'NUIGadgetLifecycleState.Destroyed' state will not be emitted.
         /// </summary>
         /// <since_tizen> 10 </since_tizen>
         protected virtual void OnDestroy()

src/Tizen.NUI.Gadget/Tizen.NUI/NUIGadgetInfo.cs

@@ -26,7 +26,7 @@
 namespace Tizen.NUI
 {
     /// <summary>
-    /// This class provides properties to get information the gadget.
+    /// This class provides properties to retrieve information the gadget.
     /// </summary>
     /// <since_tizen> 10 </since_tizen>
     [EditorBrowsable(EditorBrowsableState.Never)]

src/Tizen.NUI.Gadget/Tizen.NUI/NUIGadgetLifecycleChangedEventArgs.cs

@@ -20,20 +20,20 @@
 namespace Tizen.NUI
 {
     /// <summary>
-    /// Arguments for the event raised when the NUIGadget lifecycle is changed.
+    /// Event arguments for the NUIGadget lifecycle change event.
     /// </summary>
     /// <since_tizen> 10 </since_tizen>
     [EditorBrowsable(EditorBrowsableState.Never)]
     public class NUIGadgetLifecycleChangedEventArgs : EventArgs
     {
         /// <summary>
-        /// The NUIGadget object.
+        /// Gets the NUIGadget object that triggered the event.
         /// </summary>
         /// <since_tizen> 10 </since_tizen>
         public NUIGadget Gadget { get; internal set; }
 
         /// <summary>
-        /// The state of the NUIGadget lifecycle.
+        /// Gets the current state of the NUIGadget lifecycle.
         /// </summary>
         /// <since_tizen> 10 </since_tizen>
         public NUIGadgetLifecycleState State { get; internal set; }

src/Tizen.NUI.Gadget/Tizen.NUI/NUIGadgetManager.cs

@@ -31,7 +31,7 @@
 namespace Tizen.NUI
 {
     /// <summary>
-    /// This class has the methods and events of the NUIGadgetManager.
+    /// The NUIGadgetManager provides methods and events related to managing gadgets in the NUI.
     /// </summary>
     /// <since_tizen> 10 </since_tizen>
     [EditorBrowsable(EditorBrowsableState.Never)]
@@ -109,6 +109,10 @@ private static void OnDeviceOrientationChanged(object sender, DeviceOrientationE
         /// <summary>
         /// Occurs when the lifecycle of the NUIGadget is changed.
         /// </summary>
+        /// <remarks>
+        /// This event is raised when the state of the NUIGadget changes.
+        /// It provides information about the current state through the NUIGadgetLifecycleChangedEventArgs argument.
+        /// </remarks>
         /// <since_tizen> 10 </since_tizen>
         public static event EventHandler<NUIGadgetLifecycleChangedEventArgs> NUIGadgetLifecycleChanged;
 
@@ -137,6 +141,10 @@ private static NUIGadgetInfo Find(string resourceType)
         /// Loads an assembly of the NUIGadget.
         /// </summary>
         /// <param name="resourceType">The resource type of the NUIGadget package.</param>
+        /// <remarks>
+        /// This method loads an assembly of the NUIGadget based on the specified resource type.
+        /// It throws an ArgumentException if the argument is invalid, or an InvalidOperationException if the operation fails due to any reason.
+        /// </remarks>
         /// <exception cref="ArgumentException">Thrown when failed because of a invalid argument.</exception>
         /// <exception cref="InvalidOperationException">Thrown when failed because of an invalid operation.</exception>
         /// <since_tizen> 10 </since_tizen>
@@ -149,9 +157,9 @@ public static void Load(string resourceType)
         /// Loads an assembly of the NUIGadget.
         /// </summary>
         /// <param name="resourceType">The resource type of the NUIGadget package.</param>
-        /// <param name="useDefaultContext">The flag if ture, use a default load context. Otherwise, use a new load context.</param>
-        /// <exception cref="ArgumentException">Thrown when failed because of a invalid argument.</exception>
-        /// <exception cref="InvalidOperationException">Thrown when failed because of an invalid operation.</exception>
+        /// <param name="useDefaultContext">Indicates whether to use a default load context or not.</param>
+        /// <exception cref="ArgumentException">Thrown when failed due to an invalid argument.</exception>
+        /// <exception cref="InvalidOperationException">Thrown when failed due to an invalid operation.</exception>
         /// <since_tizen> 10 </since_tizen>
         public static void Load(string resourceType, bool useDefaultContext)
         {
@@ -165,10 +173,23 @@ public static void Load(string resourceType, bool useDefaultContext)
         }
 
         /// <summary>
-        /// Unloads the loaded assembly of the NUIGadget.
+        /// Unloads the specified NUIGadget assembly from memory.
         /// </summary>
-        /// <param name="resourceType">The resource type of the NUIGadget package.</param>
-        /// <exception cref="ArgumentException">Thrown when failed because of a invalid argument.</exception>
+        /// <remarks>
+        /// To use this method properly, the assembly of the gadget must be loaded using Load() with the custom context.
+        /// </remarks>
+        /// <param name="resourceType">The resource type of the NUIGadget package to unload.</param>
+        /// <exception cref="ArgumentException">Thrown when the argument passed is not valid.</exception>
+        /// <example>
+        /// <code>
+        /// /// Load an assembly of the NUIGadget.
+        /// NUIGadgetManager.Load("org.tizen.appfw.gadget.NetworkSetting", false);
+        /// /// NUIGadgetManager.Add("org.tizen.appfw.gadget.NetworkSetting", "NetworkSettingGadget", false);
+        ///
+        /// /// Unload the loaded assembly
+        /// NUIGadgetManager.Unload("org.tizen.appfw.gadget.NetworkSetting");
+        /// </code>
+        /// </example>
         /// <since_tizen> 10 </since_tizen>
         public static void Unload(string resourceType)
         {
@@ -257,6 +278,9 @@ public static NUIGadget Add(string resourceType, string className)
         /// <summary>
         /// Adds a NUIGadget to the NUIGadgetManager.
         /// </summary>
+        /// <remarks>
+        /// To use Unload() method, the useDefaultContext must be'false'.
+        /// </remarks>
         /// <param name="resourceType">The resource type of the NUIGadget package.</param>
         /// <param name="className">The class name of the NUIGadget.</param>
         /// <param name="useDefaultContext">The flag it true, use a default context. Otherwise, use a new load context.</param>
@@ -294,34 +318,40 @@ public static NUIGadget Add(string resourceType, string className, bool useDefau
         }
 
         /// <summary>
-        /// Gets the instance of the running NUIGadgets.
+        /// Retrieves the instances of currently running NUIGadgets.
         /// </summary>
-        /// <returns>The NUIGadget list.</returns>
+        /// <returns>An enumerable list containing all the active NUIGadgets.</returns>
         /// <since_tizen> 10 </since_tizen>
         public static IEnumerable<NUIGadget> GetGadgets()
         {
             return _gadgets;
         }
 
         /// <summary>
-        /// Gets the information of the available NUIGadgets.
+        /// Retrieves information about available NUIGadgets.
         /// </summary>
         /// <remarks>
-        /// This method only returns the available gadget informations, not all installed gadget informations.
-        /// The resource package of the NUIGadget can set the allowed packages using "allowed-package".
-        /// When executing an application, the platform mounts the resource package into the resource path of the application.
+        /// This method provides details on gadgets that are currently accessible rather than listing all installed gadgets.
+        /// A NUIGadget's resource package may specify which applications have access through the "allowed-packages" setting.
+        /// During execution, the platform mounts the resource package in the application's resources directory.
         /// </remarks>
-        /// <returns>The NUIGadgetInfo list.</returns>
+        /// <returns>An enumerable list of NUIGadgetInfo objects.</returns>
         /// <since_tizen> 10 </since_tizen>
         public static IEnumerable<NUIGadgetInfo> GetGadgetInfos()
         {
             return _gadgetInfos.Values.ToList();
         }
 
         /// <summary>
-        /// Removes the NUIGadget from the NUIGadgetManager.
+        /// Removes the specified NUIGadget from the NUIGadgetManager.
         /// </summary>
-        /// <param name="gadget">The NUIGadget object.</param>
+        /// <param name="gadget">The NUIGadget object that needs to be removed.</param>
+        /// <remarks>
+        /// This method allows you to remove a specific NUIGadget from the NUIGadgetManager.
+        /// By passing the NUIGadget object as an argument, you can ensure that only the desired gadget is removed.
+        /// It is important to note that once a gadget is removed, any references to it become invalid.
+        /// Therefore, it is crucial to handle the removal process carefully to avoid any potential issues.
+        /// </remarks>
         /// <since_tizen> 10 </since_tizen>
         public static void Remove(NUIGadget gadget)
         {
@@ -345,6 +375,10 @@ public static void Remove(NUIGadget gadget)
         /// <summary>
         /// Removes all NUIGadgets from the NUIGadgetManager.
         /// </summary>
+        /// <remarks>
+        /// This method is called to remove all NUIGadgets that are currently registered in the NUIGadgetManager.
+        /// It ensures that no more NUIGadgets exist after calling this method.
+        /// </remarks>
         /// <since_tizen> 10 </since_tizen>
         public static void RemoveAll()
         {
@@ -355,12 +389,33 @@ public static void RemoveAll()
         }
 
         /// <summary>
-        /// Resumes the running NUIGadget.
+        /// Resumes the execution of the specified NUIGadget.
         /// </summary>
-        /// <param name="gadget">The NUIGadget object.</param>
+        /// <remarks>
+        /// By calling this method, you can resume the execution of the currently suspended NUIGadget.
+        /// It takes the NUIGadget object as an argument which represents the target gadget that needs to be resumed.
+        /// </remarks>
+        /// <param name="gadget">The NUIGadget object whose execution needs to be resumed.</param>
+        /// <exception cref="ArgumentNullException">Thrown if the 'gadget' argument is null.</exception>
+        /// <example>
+        /// To resume the execution of a specific NUIGadget named 'MyGadget', you can call the following code snippet:
+        ///
+        /// <code>
+        /// // Get the reference to the NUIGadget object
+        /// NUIGadget MyGadget = ...;
+        ///
+        /// // Resume its execution
+        /// GadgetResume(MyGadget);
+        /// </code>
+        /// </example>
         /// <since_tizen> 10 </since_tizen>
         public static void Resume(NUIGadget gadget)
         {
+            if (gadget == null)
+            {
+                throw new ArgumentNullException(nameof(gadget));
+            }
+
             if (!_gadgets.Contains(gadget))
             {
                 return;
@@ -374,12 +429,21 @@ public static void Resume(NUIGadget gadget)
         }
 
         /// <summary>
-        /// Pauses the running NUIGadget.
+        /// Pauses the execution of the specified NUIGadget.
         /// </summary>
-        /// <param name="gadget">The NUIGadget object.</param>
+        /// <remarks>
+        /// Calling this method pauses the currently executing NUIGadget. It does not affect any other gadgets that may be running simultaneously.
+        /// </remarks>
+        /// <param name="gadget">The NUIGadget object whose execution needs to be paused.</param>
+        /// <exception cref="ArgumentNullException">Thrown if the argument 'gadget' is null.</exception>
         /// <since_tizen> 10 </since_tizen>
         public static void Pause(NUIGadget gadget)
         {
+            if (gadget == null)
+            {
+                throw new ArgumentNullException(nameof(gadget));
+            }
+
             if (!_gadgets.Contains(gadget))
             {
                 return;
@@ -393,12 +457,12 @@ public static void Pause(NUIGadget gadget)
         }
 
         /// <summary>
-        /// Sends the appcontrol to the running NUIGadget.
+        /// Sends the specified application control to the currently running NUIGadget.
         /// </summary>
-        /// <param name="gadget">The NUIGadget object.</param>
-        /// <param name="appControl">The appcontrol object.</param>
-        /// <exception cref="ArgumentException">Thrown when failed because of a invalid argument.</exception>
-        /// <exception cref="ArgumentNullException">Thrown when failed because the argument is null.</exception>
+        /// <param name="gadget">The NUIGadget object that will receive the app control.</param>
+        /// <param name="appControl">The app control object containing the desired arguments and actions.</param>
+        /// <exception cref="ArgumentException">Thrown if any of the arguments are invalid or missing.</exception>
+        /// <exception cref="ArgumentNullException">Thrown if either 'gadget' or 'appControl' is null.</exception>
         /// <since_tizen> 10 </since_tizen>
         public static void SendAppControl(NUIGadget gadget, AppControl appControl)
         {