From 3403b53ff44a3fdfcf0d18d290fd91330348955b Mon Sep 17 00:00:00 2001 From: hjhun <36876573+hjhun@users.noreply.github.com> Date: Mon, 30 Sep 2024 15:02:45 +0900 Subject: [PATCH] [NUI.Gadget] Enhance API descriptions (#6375) Signed-off-by: Hwankyu Jhun --- src/Tizen.NUI.Gadget/Tizen.NUI/NUIGadget.cs | 50 ++++++-- .../Tizen.NUI/NUIGadgetInfo.cs | 2 +- .../NUIGadgetLifecycleChangedEventArgs.cs | 6 +- .../Tizen.NUI/NUIGadgetManager.cs | 114 ++++++++++++++---- .../Tizen.NUI/NUIGadgetResourceManager.cs | 48 +++++--- 5 files changed, 164 insertions(+), 56 deletions(-) diff --git a/src/Tizen.NUI.Gadget/Tizen.NUI/NUIGadget.cs b/src/Tizen.NUI.Gadget/Tizen.NUI/NUIGadget.cs index 6a766047b51..2f48cca2ee2 100755 --- a/src/Tizen.NUI.Gadget/Tizen.NUI/NUIGadget.cs +++ b/src/Tizen.NUI.Gadget/Tizen.NUI/NUIGadget.cs @@ -22,8 +22,13 @@ namespace Tizen.NUI { /// - /// This class represents a NUIGadget controlled lifecycles. + /// Represents a NUIGadget controlled lifecycle. /// + /// + /// 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. + /// /// 10 [EditorBrowsable(EditorBrowsableState.Never)] public abstract class NUIGadget @@ -31,7 +36,11 @@ public abstract class NUIGadget /// /// Initializes the gadget. /// - /// /// The type of the NUIGadget. + /// The type of the NUIGadget. + /// + /// 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. + /// /// 10 public NUIGadget(NUIGadgetType type) { @@ -44,7 +53,11 @@ public NUIGadget(NUIGadgetType type) /// /// Gets the class representing information of the current gadget. /// - /// This property is set before the OnCreate() is called, after the instance has been created. + /// + /// 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. + /// /// 10 public NUIGadgetInfo NUIGadgetInfo { @@ -53,7 +66,7 @@ public NUIGadgetInfo NUIGadgetInfo } /// - /// Gets the type. + /// Gets the type of the NUI gadget. /// /// 10 public NUIGadgetType Type @@ -65,7 +78,10 @@ public NUIGadgetType Type /// /// Gets the class name. /// - /// This property is set before the OnCreate() is called, after the instance has been created. + /// + /// 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. + /// /// 10 public string ClassName { @@ -74,7 +90,7 @@ public string ClassName } /// - /// Gets the main view. + /// Gets the main view of the NUI gadget.. /// /// 10 public View MainView @@ -84,7 +100,7 @@ public View MainView } /// - /// Gets the lifecycle state. + /// Gets the current lifecycle state of the gadget. /// /// 10 public NUIGadgetLifecycleState State @@ -96,7 +112,11 @@ public NUIGadgetLifecycleState State /// /// Gets the resource manager. /// - /// This property is set before the OnCreate() is called, after the instance has been created. + /// 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. + /// /// 10 public NUIGadgetResourceManager NUIGadgetResourceManager { @@ -172,8 +192,8 @@ private void NotifyLifecycleChanged() } /// - /// 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. /// /// The main view object. /// 10 @@ -187,15 +207,19 @@ protected virtual Tizen.NUI.BaseComponents.View OnCreate() /// /// Overrides this method if want to handle behavior when the gadget receives the appcontrol message. /// - /// The appcontrol received event argument. + /// + /// 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. + /// + /// The appcontrol received event argument containing details about the received message. /// 10 protected virtual void OnAppControlReceived(AppControlReceivedEventArgs e) { } /// - /// 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. /// /// 10 protected virtual void OnDestroy() diff --git a/src/Tizen.NUI.Gadget/Tizen.NUI/NUIGadgetInfo.cs b/src/Tizen.NUI.Gadget/Tizen.NUI/NUIGadgetInfo.cs index dcd551f43d3..c28aaa88a19 100755 --- a/src/Tizen.NUI.Gadget/Tizen.NUI/NUIGadgetInfo.cs +++ b/src/Tizen.NUI.Gadget/Tizen.NUI/NUIGadgetInfo.cs @@ -26,7 +26,7 @@ namespace Tizen.NUI { /// - /// This class provides properties to get information the gadget. + /// This class provides properties to retrieve information the gadget. /// /// 10 [EditorBrowsable(EditorBrowsableState.Never)] diff --git a/src/Tizen.NUI.Gadget/Tizen.NUI/NUIGadgetLifecycleChangedEventArgs.cs b/src/Tizen.NUI.Gadget/Tizen.NUI/NUIGadgetLifecycleChangedEventArgs.cs index 2db245cd121..9c9e063f757 100755 --- a/src/Tizen.NUI.Gadget/Tizen.NUI/NUIGadgetLifecycleChangedEventArgs.cs +++ b/src/Tizen.NUI.Gadget/Tizen.NUI/NUIGadgetLifecycleChangedEventArgs.cs @@ -20,20 +20,20 @@ namespace Tizen.NUI { /// - /// Arguments for the event raised when the NUIGadget lifecycle is changed. + /// Event arguments for the NUIGadget lifecycle change event. /// /// 10 [EditorBrowsable(EditorBrowsableState.Never)] public class NUIGadgetLifecycleChangedEventArgs : EventArgs { /// - /// The NUIGadget object. + /// Gets the NUIGadget object that triggered the event. /// /// 10 public NUIGadget Gadget { get; internal set; } /// - /// The state of the NUIGadget lifecycle. + /// Gets the current state of the NUIGadget lifecycle. /// /// 10 public NUIGadgetLifecycleState State { get; internal set; } diff --git a/src/Tizen.NUI.Gadget/Tizen.NUI/NUIGadgetManager.cs b/src/Tizen.NUI.Gadget/Tizen.NUI/NUIGadgetManager.cs index c0289ea0bb4..e7e277d33df 100755 --- a/src/Tizen.NUI.Gadget/Tizen.NUI/NUIGadgetManager.cs +++ b/src/Tizen.NUI.Gadget/Tizen.NUI/NUIGadgetManager.cs @@ -31,7 +31,7 @@ namespace Tizen.NUI { /// - /// This class has the methods and events of the NUIGadgetManager. + /// The NUIGadgetManager provides methods and events related to managing gadgets in the NUI. /// /// 10 [EditorBrowsable(EditorBrowsableState.Never)] @@ -109,6 +109,10 @@ private static void OnDeviceOrientationChanged(object sender, DeviceOrientationE /// /// Occurs when the lifecycle of the NUIGadget is changed. /// + /// + /// This event is raised when the state of the NUIGadget changes. + /// It provides information about the current state through the NUIGadgetLifecycleChangedEventArgs argument. + /// /// 10 public static event EventHandler NUIGadgetLifecycleChanged; @@ -137,6 +141,10 @@ private static NUIGadgetInfo Find(string resourceType) /// Loads an assembly of the NUIGadget. /// /// The resource type of the NUIGadget package. + /// + /// 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. + /// /// Thrown when failed because of a invalid argument. /// Thrown when failed because of an invalid operation. /// 10 @@ -149,9 +157,9 @@ public static void Load(string resourceType) /// Loads an assembly of the NUIGadget. /// /// The resource type of the NUIGadget package. - /// The flag if ture, use a default load context. Otherwise, use a new load context. - /// Thrown when failed because of a invalid argument. - /// Thrown when failed because of an invalid operation. + /// Indicates whether to use a default load context or not. + /// Thrown when failed due to an invalid argument. + /// Thrown when failed due to an invalid operation. /// 10 public static void Load(string resourceType, bool useDefaultContext) { @@ -165,10 +173,23 @@ public static void Load(string resourceType, bool useDefaultContext) } /// - /// Unloads the loaded assembly of the NUIGadget. + /// Unloads the specified NUIGadget assembly from memory. /// - /// The resource type of the NUIGadget package. - /// Thrown when failed because of a invalid argument. + /// + /// To use this method properly, the assembly of the gadget must be loaded using Load() with the custom context. + /// + /// The resource type of the NUIGadget package to unload. + /// Thrown when the argument passed is not valid. + /// + /// + /// /// 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"); + /// + /// /// 10 public static void Unload(string resourceType) { @@ -257,6 +278,9 @@ public static NUIGadget Add(string resourceType, string className) /// /// Adds a NUIGadget to the NUIGadgetManager. /// + /// + /// To use Unload() method, the useDefaultContext must be'false'. + /// /// The resource type of the NUIGadget package. /// The class name of the NUIGadget. /// The flag it true, use a default context. Otherwise, use a new load context. @@ -294,9 +318,9 @@ public static NUIGadget Add(string resourceType, string className, bool useDefau } /// - /// Gets the instance of the running NUIGadgets. + /// Retrieves the instances of currently running NUIGadgets. /// - /// The NUIGadget list. + /// An enumerable list containing all the active NUIGadgets. /// 10 public static IEnumerable GetGadgets() { @@ -304,14 +328,14 @@ public static IEnumerable GetGadgets() } /// - /// Gets the information of the available NUIGadgets. + /// Retrieves information about available NUIGadgets. /// /// - /// 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. /// - /// The NUIGadgetInfo list. + /// An enumerable list of NUIGadgetInfo objects. /// 10 public static IEnumerable GetGadgetInfos() { @@ -319,9 +343,15 @@ public static IEnumerable GetGadgetInfos() } /// - /// Removes the NUIGadget from the NUIGadgetManager. + /// Removes the specified NUIGadget from the NUIGadgetManager. /// - /// The NUIGadget object. + /// The NUIGadget object that needs to be removed. + /// + /// 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. + /// /// 10 public static void Remove(NUIGadget gadget) { @@ -345,6 +375,10 @@ public static void Remove(NUIGadget gadget) /// /// Removes all NUIGadgets from the NUIGadgetManager. /// + /// + /// 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. + /// /// 10 public static void RemoveAll() { @@ -355,12 +389,33 @@ public static void RemoveAll() } /// - /// Resumes the running NUIGadget. + /// Resumes the execution of the specified NUIGadget. /// - /// The NUIGadget object. + /// + /// 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. + /// + /// The NUIGadget object whose execution needs to be resumed. + /// Thrown if the 'gadget' argument is null. + /// + /// To resume the execution of a specific NUIGadget named 'MyGadget', you can call the following code snippet: + /// + /// + /// // Get the reference to the NUIGadget object + /// NUIGadget MyGadget = ...; + /// + /// // Resume its execution + /// GadgetResume(MyGadget); + /// + /// /// 10 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) } /// - /// Pauses the running NUIGadget. + /// Pauses the execution of the specified NUIGadget. /// - /// The NUIGadget object. + /// + /// Calling this method pauses the currently executing NUIGadget. It does not affect any other gadgets that may be running simultaneously. + /// + /// The NUIGadget object whose execution needs to be paused. + /// Thrown if the argument 'gadget' is null. /// 10 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) } /// - /// Sends the appcontrol to the running NUIGadget. + /// Sends the specified application control to the currently running NUIGadget. /// - /// The NUIGadget object. - /// The appcontrol object. - /// Thrown when failed because of a invalid argument. - /// Thrown when failed because the argument is null. + /// The NUIGadget object that will receive the app control. + /// The app control object containing the desired arguments and actions. + /// Thrown if any of the arguments are invalid or missing. + /// Thrown if either 'gadget' or 'appControl' is null. /// 10 public static void SendAppControl(NUIGadget gadget, AppControl appControl) { diff --git a/src/Tizen.NUI.Gadget/Tizen.NUI/NUIGadgetResourceManager.cs b/src/Tizen.NUI.Gadget/Tizen.NUI/NUIGadgetResourceManager.cs index d99a2c382e8..6f20fba2bfc 100755 --- a/src/Tizen.NUI.Gadget/Tizen.NUI/NUIGadgetResourceManager.cs +++ b/src/Tizen.NUI.Gadget/Tizen.NUI/NUIGadgetResourceManager.cs @@ -25,7 +25,7 @@ namespace Tizen.NUI { /// - /// This class has the methods of the NUIGadgetResourceManager. + /// Manages resources related to NUI gadgets. /// /// 10 [EditorBrowsable(EditorBrowsableState.Never)] @@ -40,8 +40,8 @@ public class NUIGadgetResourceManager /// Initializes the resource manager of the gadget. /// /// The information of the gadget. - /// Thrown when failed because of a invalid argument. - /// 11 + /// Thrown when the argument is not valid. + /// 10 public NUIGadgetResourceManager(NUIGadgetInfo info) { if (info == null) @@ -57,9 +57,9 @@ public NUIGadgetResourceManager(NUIGadgetInfo info) /// /// Initializes the resource manager of the gadget. /// - /// The path of the resource - /// The file name of the resource. - /// The class name of the resource. + /// The path where the resources are located. + /// The name of the DLL containing the resources. + /// The name of the class that represents the resources. /// 10 public NUIGadgetResourceManager(string resourcePath, string resourceDll, string resourceClassName) { @@ -69,10 +69,26 @@ public NUIGadgetResourceManager(string resourcePath, string resourceDll, string } /// - /// Get the value of the specified string resource. + /// Retrieves the value of the specified string resource. /// - /// The name of the resource to retrieve. - /// The value of the resource, or null if name cannot be found in a resource set. + /// The unique identifier for the string resource to retrieve. + /// The value of the requested string resource, or null if no matching resource could be found. + /// + /// This function allows you to access localized string resources by providing their names. + /// It returns the actual value of the requested resource, which can then be displayed to users or used elsewhere in your application logic. + /// If the specified resource does not exist or cannot be found, the function will return null instead. + /// + /// + /// Here's an example demonstrating how to retrieve a string resource named "greeting" from the current context: + /// + /// + /// // Retrieve the greeting message + /// string greetingMessage = GetString("greeting"); + /// + /// // Display the greeting message to the user + /// Console.WriteLine(greetingMessage); + /// + /// /// 10 public string GetString(string name) { @@ -80,12 +96,16 @@ public string GetString(string name) } /// - /// Gets the return value of the string resource localized for the specified culture. + /// Retrieves the localized string resource for the specified culture. /// - /// The name of the resource to retrieve. - /// An object that represents the culture for which the resource is localied. - /// The value of the resource localied for the specified culture, or null if name cannot be found in a resource set. - /// Thrown when failed because of a invalid argument. + /// + /// This method enables you to obtain a localized version of a specific string resource based on the provided culture. + /// It returns the desired resource value or null if the requested resource cannot be found in the resource set. + /// + /// The name of the resource to fetch. + /// An object representing the culture for which the resource needs to be localized. + /// The localized string resource for the specified culture, or null if the resource cannot be found. + /// Thrown when an invalid argument causes failure. /// 10 public string GetString(string name, CultureInfo cultureInfo) {