[Applications.ComponentBased] Enhance API descriptions

Signed-off-by: Changgyu Choi <[email protected]>

src/Tizen.Applications.ComponentBased/Tizen.Applications.ComponentBased.Common/BaseComponent.cs

@@ -21,11 +21,11 @@
 namespace Tizen.Applications.ComponentBased.Common
 {
     /// <summary>
-    /// This is a base-component class.
-    /// It provides common functions of FrameComponent and ServiceComponent.
+    /// Represents the base class for components, providing common functionalities for both FrameComponent and ServiceComponent.
     /// </summary>
     /// <remarks>
-    /// This class cannot be registered by ComponentBased applications.
+    /// This class cannot be registered directly by ComponentBased applications.
+    /// It serves as a base class to be inherited by other components.
     /// </remarks>
     /// <since_tizen> 6 </since_tizen>
     public abstract class BaseComponent
@@ -75,26 +75,26 @@ public abstract class BaseComponent
         public event EventHandler<TimeZoneChangedEventArgs> TimeZoneChanged;
 
         /// <summary>
-        /// A component instance ID.
+        /// Gets the unique instance ID of the component.
         /// It will be created after OnCreate method is invoked.
         /// </summary>
         /// <since_tizen> 6 </since_tizen>
         public string Id { get; private set; }
 
         /// <summary>
-        /// A component ID
+        /// Gets the ID of the component.
         /// </summary>
         /// <since_tizen> 6 </since_tizen>
         public string ComponentId { get; private set; }
 
         /// <summary>
-        /// Parent object
+        /// Gets the parent application object to which the component belongs.
         /// </summary>
         /// <since_tizen> 6 </since_tizen>
         public ComponentBasedApplication Parent { get; private set; }
 
         /// <summary>
-        /// Finish current component
+        /// Finishes the current component.
         /// </summary>
         /// <since_tizen> 6 </since_tizen>
         public void Finish()
@@ -128,18 +128,18 @@ internal void Bind(IntPtr handle, string compId, string instanceId, ComponentBas
         }
 
         /// <summary>
-        /// Overrides this method if want to handle behavior to restore the previous status.
+        /// Override this method to handle restoring the previous state of the component.
         /// </summary>
-        /// <param name="c">Contents. It can be used only in the callback. To use outside, make a copy. </param>
+        /// <param name="c">A bundle containing the saved state of the component. It can only be used within the callback. To use it outside, create a copy.</param>
         /// <since_tizen> 6 </since_tizen>
         public virtual void OnRestoreContents(Bundle c)
         {
         }
 
         /// <summary>
-        /// Overrides this method if want to handle behavior to save current status.
+        /// Override this method to handle saving the current state of the component.
         /// </summary>
-        /// <param name="c">Contents. It can be used only in the callback. To use outside, make a copy. </param>
+        /// <param name="c">A bundle containing the current state of the component. It can only be used within the callback. To use it outside, create a copy.</param>
         /// <since_tizen> 6 </since_tizen>
         public virtual void OnSaveContent(Bundle c)
         {
@@ -181,17 +181,18 @@ internal void OnTimeZoneChangedCallback(string timeZone, string timeZoneId)
         }
 
         /// <summary>
-        /// Sends the launch request asynchronously.
+        /// Sends a launch request asynchronously.
         /// </summary>
         /// <remarks>
-        /// To use group mode, you must use this function instead of SendLaunchRequestAsync().
+        /// Use this method to send a launch request with group mode enabled.
+        /// If group mode is not required, you can use SendLaunchRequestAsync() instead.
         /// </remarks>
-        /// <param name="control">appcontrol object</param>
-        /// <param name="replyAfterLaunching">The callback function to be called when the reply is delivered.</param>
-        /// <returns>A task with the result of the launch request.</returns>
+        /// <param name="control">The AppControl object representing the request details.</param>
+        /// <param name="replyAfterLaunching">The callback function to be invoked when the reply is received.</param>
+        /// <returns>A task representing the result of the launch request.</returns>
         /// <exception cref="ArgumentException">Thrown when failed because of the argument is invalid.</exception>
-        /// <exception cref="InvalidOperationException">Thrown when fail to set component information to the AppControl.</exception>
-        /// <exception cref="Exceptions.AppNotFoundException">Thrown when the application to run is not found.</exception>
+        /// <exception cref="InvalidOperationException">Thrown when there is a failure in setting the component information in the AppControl.</exception>
+        /// <exception cref="Exceptions.AppNotFoundException">Thrown when the target application is not found.</exception>
         /// <exception cref="Exceptions.LaunchRejectedException">Thrown when the launch request is rejected.</exception>
         /// <privilege>http://tizen.org/privilege/appmanager.launch</privilege>
         /// <since_tizen> 6 </since_tizen>

src/Tizen.Applications.ComponentBased/Tizen.Applications.ComponentBased.Common/ComponentBasedApplication.cs

@@ -20,8 +20,13 @@
 namespace Tizen.Applications.ComponentBased.Common
 {
     /// <summary>
-    /// The class for supporting multi-components based application model.
+    /// Represents the base class for a multi-component based application.
+    /// This class allows the creation and management of multiple application components, such as Frame, Service, and Widget components.
     /// </summary>
+    /// <remarks>
+    /// This abstract class provides the core structure for applications that consist of multiple components.
+    /// Each component has its own lifecycle, and the framework handles these lifecycles independently.
+    /// </remarks>
     /// <since_tizen> 6 </since_tizen>
     public abstract class ComponentBasedApplication : Application
     {
@@ -30,12 +35,24 @@ public abstract class ComponentBasedApplication : Application
         private Interop.CBApplication.CBAppLifecycleCallbacks _callbacks;
 
         /// <summary>
-        /// Initializes the ComponentBasedApplicationBase class.
+        /// Initializes a new instance of the <see cref="ComponentBasedApplication"/> class with the specified component type information.
         /// </summary>
-        /// <param name="typeInfo">The component type information.
-        /// The key should be a class type of FrameComponent or SubComponent subclass.
-        /// The value should be a component id which is declared in tizen-manifest.xml.
-        /// </param>
+        /// <param name="typeInfo">A dictionary where the key is the component class type (FrameComponent, ServiceComponent or WidgetComponent subclass),
+        /// and the value is the component ID defined in the tizen-manifest.xml file.</param>
+        /// <remarks>
+        /// This constructor sets up the necessary callbacks for the application lifecycle and registers the provided components.
+        /// </remarks>
+        /// <example>
+        /// <code>
+        /// IDictionary&lt;Type, string&gt; components = new Dictionary&lt;Type, string&gt;()
+        /// {
+        ///     { typeof(MyFrameComponent), "frameComponentId" },
+        ///     { typeof(MyServiceComponent), "serviceComponentId" }
+        /// };
+        /// ComponentBasedApplication app = new MyApplication(components);
+        /// app.Run(args);
+        /// </code>
+        /// </example>
         /// <since_tizen> 6 </since_tizen>
         public ComponentBasedApplication(IDictionary<Type, string> typeInfo)
         {
@@ -53,11 +70,19 @@ public ComponentBasedApplication(IDictionary<Type, string> typeInfo)
         }
 
         /// <summary>
-        /// Registers a component.
+        /// Registers a component with the specified type and ID.
         /// </summary>
-        /// <param name="compType">Class type</param>
-        /// <param name="compId">Component ID</param>
-        /// <exception cref="ArgumentException">Thrown when component type is already added or not sub-class of FrameComponent or ServiceComponent</exception>
+        /// <param name="compType">The type of the component to register. Must be a subclass of FrameComponent, ServiceComponent, or WidgetComponent.</param>
+        /// <param name="compId">The ID of the component, defined in the tizen-manifest.xml file.</param>
+        /// <exception cref="ArgumentException">Thrown when the component type is already registered or not sub-class of FrameComponent, ServiceComponent or WidgetComponent.</exception>
+        /// <remarks>
+        /// This method ensures that only valid component types are registered. The component ID must be unique.
+        /// </remarks>
+        /// <example>
+        /// <code>
+        /// app.RegisterComponent(typeof(MyFrameComponent), "frameComponentId");
+        /// </code>
+        /// </example>
         /// <since_tizen> 6 </since_tizen>
         public void RegisterComponent(Type compType, string compId)
         {
@@ -98,8 +123,13 @@ public void RegisterComponent(Type compType, string compId)
         /// <summary>
         /// Runs the application's main loop.
         /// </summary>
-        /// <param name="args">Arguments from commandline.</param>
+        /// <param name="args">The arguments passed from the command line.</param>
         /// <exception cref="InvalidOperationException">Thrown when component type is already added to the component.</exception>
+        /// <example>
+        /// <code>
+        /// app.Run(args);
+        /// </code>
+        /// </example>
         /// <since_tizen> 6 </since_tizen>
         public override void Run(string[] args)
         {
@@ -121,7 +151,7 @@ public override void Run(string[] args)
         }
 
         /// <summary>
-        /// Exits the main loop of the application.
+        /// Exits the application's main loop.
         /// </summary>
         /// <since_tizen> 6 </since_tizen>
         public override void Exit()
@@ -166,31 +196,43 @@ private void OnFinishedNative(IntPtr data)
         }
 
         /// <summary>
-        /// This method will be called before running main-loop
+        /// Called before the main loop starts.
         /// </summary>
-        /// <param name="args"></param>
+        /// <param name="args">The arguments passed from the command line.</param>
+        /// <remarks>
+        /// Override this method to handle any initialization logic before the application enters the main event loop.
+        /// </remarks>
         /// <since_tizen> 6 </since_tizen>
         protected virtual void OnInit(string[] args)
         {
         }
 
         /// <summary>
-        /// This method will be called after exiting main-loop
+        /// Called after the main loop exits.
         /// </summary>
+        /// <remarks>
+        /// Override this method to handle any cleanup logic after the application has finished running.
+        /// </remarks>
         /// <since_tizen> 6 </since_tizen>
         protected virtual void OnFinished()
         {
         }
 
         /// <summary>
-        /// This method will be called to start main-loop
+        /// Called to start the main loop of the application.
         /// </summary>
+        /// <remarks>
+        /// This is an abstract method that must be implemented by derived classes to define the behavior when the application starts.
+        /// </remarks>
         /// <since_tizen> 6 </since_tizen>
         protected abstract void OnRun();
 
         /// <summary>
-        /// This method will be called to exit main-loop
+        /// Called to exit the main loop of the application.
         /// </summary>
+        /// <remarks>
+        /// Override this method to handle any logic needed before the application exits.
+        /// </remarks>
         /// <since_tizen> 6 </since_tizen>
         protected virtual void OnExit()
         {

src/Tizen.Applications.ComponentBased/Tizen.Applications.ComponentBased.Common/FrameComponent.cs

@@ -19,15 +19,19 @@
 namespace Tizen.Applications.ComponentBased.Common
 {
     /// <summary>
-    /// The class for showing UI module
+    /// Represents a base class for UI components in the component-based application model.
+    /// This class provides methods for handling the lifecycle and state of UI components.
     /// </summary>
     /// <since_tizen> 6 </since_tizen>
     public abstract class FrameComponent : BaseComponent
     {
         /// <summary>
-        /// Gets the display status of a component.
+        /// Gets the current display status of the component.
         /// </summary>
-        /// <exception cref="InvalidOperationException">Thrown when component type is already added to the component.</exception>
+        /// <value>
+        /// The current <see cref="DisplayStatus"/> of the component.
+        /// </value>
+        /// <exception cref="InvalidOperationException">Thrown when the display status cannot be retrieved.</exception>
         /// <since_tizen> 6 </since_tizen>
         public DisplayStatus DisplayStatus
         {
@@ -43,55 +47,60 @@ public DisplayStatus DisplayStatus
         }
 
         /// <summary>
-        /// Overrides this method to handle behavior when the component is launched.
+        /// Called when the component is launched. Override this method to implement custom launch behavior.
         /// </summary>
-        /// <returns>True if a service component is successfully created</returns>
+        /// <returns>
+        /// <c>true</c> if the service component is successfully created; otherwise, <c>false</c>.
+        /// </returns>
         /// <since_tizen> 6 </since_tizen>
         public abstract bool OnCreate();
 
         /// <summary>
-        /// Overrides this method to create window. It will be called before OnCreate method.
+        /// Called to create the window for the component. Override this method to provide a custom window.
+        /// This method will be called before <see cref="OnCreate"/> method.
         /// </summary>
-        /// <returns>Window object to use</returns>
+        /// <returns>
+        /// An <see cref="IWindowInfo"/> object that represents the created window.
+        /// </returns>
         /// <since_tizen> 6 </since_tizen>
         public abstract IWindowInfo CreateWindowInfo();
 
         /// <summary>
-        /// Overrides this method if want to handle behavior when the component receives the appcontrol message.
+        /// Called when the component receives an app control message. Override this method to handle app control messages.
         /// </summary>
-        /// <param name="appControl">appcontrol object</param>
-        /// <param name="restarted">True if it was restarted</param>
+        /// <param name="appControl">The <see cref="AppControl"/> object containing the app control data.</param>
+        /// <param name="restarted"><c>true</c> if the component was restarted; otherwise, <c>false</c>.</param>
         /// <since_tizen> 6 </since_tizen>
         public virtual void OnStart(AppControl appControl, bool restarted)
         {
         }
 
         /// <summary>
-        /// Overrides this method if you want to handle the behavior when the component is resumed.
+        /// Called when the component is resumed. Override this method to handle resume behavior.
         /// </summary>
         /// <since_tizen> 6 </since_tizen>
         public virtual void OnResume()
         {
         }
 
         /// <summary>
-        /// Overrides this method if you want to handle the behavior when the component is paused.
+        /// Called when the component is paused. Override this method to handle pause behavior.
         /// </summary>
         /// <since_tizen> 6 </since_tizen>
         public virtual void OnPause()
         {
         }
 
         /// <summary>
-        /// Overrides this method if you want to handle the behavior when the component is stopped.
+        /// Called when the component is stopped. Override this method to handle stop behavior.
         /// </summary>
         /// <since_tizen> 6 </since_tizen>
         public virtual void OnStop()
         {
         }
 
         /// <summary>
-        /// Overrides this method if want to handle behavior when the component is destroyed.
+        /// Called when the component is destroyed. Override this method to handle destruction behavior.
         /// </summary>
         /// <since_tizen> 6 </since_tizen>
         public virtual void OnDestroy()

src/Tizen.Applications.ComponentBased/Tizen.Applications.ComponentBased.Common/ServiceComponent.cs

@@ -19,33 +19,37 @@
 namespace Tizen.Applications.ComponentBased.Common
 {
     /// <summary>
-    /// The class for showing service module
+    /// Represents a base class for service components in the component-based application model.
+    /// This class provides methods for handling the lifecycle and state of service components.
     /// </summary>
     /// <since_tizen> 6 </since_tizen>
     public abstract class ServiceComponent : BaseComponent
     {
         /// <summary>
-        /// Overrides this method to handle behavior when the component is created.
+        /// Called when the service component is created. Override this method to implement custom creation behavior.
         /// </summary>
-        /// <returns>True if a service component is successfully created</returns>
+        /// <returns>
+        /// <c>true</c> if the service component is successfully created; otherwise, <c>false</c>.
+        /// </returns>
         public abstract bool OnCreate();
 
         /// <summary>
-        /// Overrides this method if want to handle behavior when the component receives the start command message.
+        /// Called when the service component receives a start command message. Override this method to handle start command behavior.
         /// </summary>
-        /// <param name="appControl">appcontrol object</param>
-        /// <param name="restarted">True if it was restarted</param>
+        /// <param name="appControl">The <see cref="AppControl"/> object containing the app control data.</param>
+        /// <param name="restarted"><c>true</c> if the component was restarted; otherwise, <c>false</c>.</param>
         /// <since_tizen> 6 </since_tizen>
         public virtual void OnStartCommand(AppControl appControl, bool restarted)
         {
         }
 
         /// <summary>
-        /// Overrides this method if want to handle behavior when the component is destroyed.
+        /// Called when the service component is destroyed. Override this method to handle destruction behavior.
         /// </summary>
         /// <since_tizen> 6 </since_tizen>
         public virtual void OnDestroy()
         {
         }
     }
 }
+