[Tizen.Core] Enhance API descriptions (#6378)

* [Tizen.Core] Enhance API descriptions

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

* [Tizen.Core] Add a missing '/'

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

---------

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

src/Tizen.Core/Tizen.Core/Channel.cs

@@ -21,28 +21,39 @@ namespace Tizen.Core
     /// <summary>
     /// The class for managing communication channels between tasks of Tizen Core.
     /// </summary>
+    /// <remarks>
+    /// Channels are essential in inter-task communications because they provide a reliable way to exchange messages and data.
+    /// By creating a channel, you can establish a connection between two tasks that need to communicate with each other.
+    /// Once created, both tasks can send and receive messages through the channel.
+    /// It's important to note that channels have a limited capacity, so make sure to handle message overflows appropriately.
+    /// Additionally, remember to close the channel once it's no longer needed to avoid resource leaks.
+    /// </remarks>
     /// <since_tizen> 12 </since_tizen>
     public class Channel : IDisposable
     {
         private bool _disposed = false;
 
         /// <summary>
-        /// Constructor for creating a new channel with a sender and a receiver.
+        /// Creates a new channel with a sender and a receiver.
         /// </summary>
+        /// <remarks>
+        /// This constructor initializes a new channel that enables communication between a sender and a receiver.
+        /// It throws exceptions if any errors occur during initialization due to insufficient memory or invalid operations.
+        /// </remarks>
         /// <exception cref="OutOfMemoryException">Thrown when out of memory.</exception>
         /// <exception cref="InvalidOperationException">Thrown when failed because of an invalid operation.</exception>
         /// <example>
+        /// In the following code snippet, we attempt to initialize a new channel by calling the constructor.
+        /// However, if there is not enough memory available, an OutOfMemoryException is thrown. We handle this exception by displaying a message in the console.
         /// <code>
-        /// 
         /// try
         /// {
-        ///   var channel = new Channel();
+        ///    var channel = new Channel();
         /// }
         /// catch (OutOfMemoryException)
         /// {
-        ///   Console.WriteLine("Exception occurs");
+        ///    Console.WriteLine("Exception occurs");
         /// }
-        /// 
         /// </code>
         /// </example>
         /// <since_tizen> 12 </since_tizen>
@@ -55,7 +66,7 @@ public Channel()
         }
 
         /// <summary>
-        /// Finalizer of the class Channel.
+        /// Finalizes an instance of the Channel class.
         /// </summary>
         ~Channel()
         {
@@ -65,12 +76,21 @@ public Channel()
         /// <summary>
         /// Gets the channel sender instance.
         /// </summary>
+        /// <remarks>
+        /// This property provides access to the channel sender instance that can be used to send messages through the specified channel.
+        /// It ensures that only one sender instance per channel exists in order to avoid any conflicts during message transmission.
+        /// </remarks>
         /// <since_tizen> 12 </since_tizen>
         public ChannelSender Sender { get; private set; }
 
         /// <summary>
-        /// Gets the channel receiver instance. 
+        /// Gets the channel receiver instance.
         /// </summary>
+        /// <remarks>
+        /// This property provides access to the channel receiver instance that handles incoming messages from other applications.
+        /// By utilizing this instance, you can subscribe to specific channels and receive notifications accordingly.
+        /// It is crucial to understand the concept of channels in order to effectively utilize this feature. For more details on channels, refer to the official documentation.
+        /// </remarks>
         /// <since_tizen> 12 </since_tizen>
         public ChannelReceiver Receiver { get; private set; }
 

src/Tizen.Core/Tizen.Core/ChannelObject.cs

@@ -24,6 +24,11 @@ namespace Tizen.Core
     /// <summary>
     /// Represents a channel object used for inter-task communication.
     /// </summary>
+    /// <remarks>
+    /// A channel object provides a mechanism for tasks to communicate with each other in a process. It allows sending messages between tasks without any race conditions.
+    /// To create a channel object, call the static method 'Create'. Once created, you can send and receive messages through the channel by calling the respective methods on the channel object.
+    /// When you are done using the channel object, remember to dispose it properly to avoid resource leaks.
+    /// </remarks>
     /// <since_tizen> 12 </since_tizen>
     public class ChannelObject : IDisposable
     {
@@ -40,6 +45,10 @@ public class ChannelObject : IDisposable
         /// <param name="data">The data object.</param>
         /// <exception cref="OutOfMemoryException">Thrown when out of memory.</exception>
         /// <exception cref="InvalidOperationException">Thrown when failed because of an invalid operation.</exception>
+        /// <remarks>
+        /// This constructor creates a new channel object with the specified ID and data. It throws an OutOfMemoryException if there isn't enough memory available to allocate the object.
+        /// Additionally, it may throw an InvalidOperationException if the operation fails due to an invalid condition.
+        /// </remarks>
         /// <example>
         /// <code>
         /// 
@@ -68,7 +77,7 @@ internal ChannelObject(IntPtr handle)
         }
 
         /// <summary>
-        /// Finalizer of the class ChannelObject.
+        /// Finalizes an instance of the ChannelObject class.
         /// </summary>
         ~ChannelObject()
         {
@@ -135,7 +144,8 @@ public object Data
         /// Gets the name of the sender task.
         /// </summary>
         /// <since_tizen> 12 </since_tizen>
-        public string Sender {
+        public string Sender
+        {
             get
             {
                 Interop.LibTizenCore.TizenCoreChannel.ObjectGetSenderTaskName(_handle, out IntPtr taskName);

src/Tizen.Core/Tizen.Core/ChannelReceivedEventArgs.cs

@@ -19,7 +19,7 @@
 namespace Tizen.Core
 {
     /// <summary>
-    /// Arguments for the event raised when an object has been received through a channel.
+    /// Represents the arguments for the event raised when an object has been received through a channel.
     /// </summary>
     /// <since_tizen> 12 </since_tizen>
     public class ChannelReceivedEventArgs : System.EventArgs

src/Tizen.Core/Tizen.Core/ChannelReceiver.cs

@@ -35,15 +35,15 @@ internal ChannelReceiver(IntPtr handle)
         }
 
         /// <summary>
-        /// Finalizer of the class ChannelReceiver.
+        /// Finalizes an instance of the ChannelReceiver class.
         /// </summary>
         ~ChannelReceiver()
         {
             Dispose(false);
         }
 
         /// <summary>
-        /// Occurrs whenever the channel object is received in the main loop of the task.
+        /// Occurs whenever a channel object is received in the main loop of the task.
         /// </summary>
         /// <remarks>
         /// The registered event handler will be invoked when the channel receiver is added to the specific task.
@@ -53,8 +53,8 @@ internal ChannelReceiver(IntPtr handle)
         /// 
         /// var channel = new Channel();
         /// var receiver = channel.Receiver;
-        /// receiver.Received += (s, e) => {
-        ///   Console.WriteLine("OnChannelObjectReceived. Message = {}", (string)e.Data);
+        /// receiver.Received += (sender, args) => {
+        ///   Console.WriteLine("OnChannelObjectReceived. Message = {0}", (string)args.Data);
         /// };
         /// 
         /// </code>
@@ -63,19 +63,23 @@ internal ChannelReceiver(IntPtr handle)
         public event EventHandler<ChannelReceivedEventArgs> Received;
 
         /// <summary>
-        /// Receives the channel object from the sender asynchronously.
+        /// Asynchronously receives the channel object from the sender.
         /// </summary>
         /// <returns>The received channel object.</returns>
         /// <exception cref="OutOfMemoryException">Thrown when out of memory.</exception>
-        /// <exception cref="InvalidOperationException">Thrown when failed because of an invalid operation.</exception>
+        /// <exception cref="InvalidOperationException">Thrown when failed due to an invalid operation.</exception>
         /// <example>
         /// <code>
         /// 
         /// var channel = new Channel();
         /// var task = TizenCore.Find("Test");
         /// task.Send(async () => {
-        ///   var channelObject = await channel.Receiver.Receive();
-        ///   Console.WriteLine("Message = {}", (string)channelObject.Data);
+        ///   try {
+        ///     var channelObject = await channel.Receiver.Receive();
+        ///     Console.WriteLine("Message = {}", (string)channelObject.Data);
+        ///   } catch (Exception e) {
+        ///     Console.Error.WriteLine("Failed to receive message: {0}", e.ToString());
+        ///   }
         /// });
         /// 
         /// </code>

src/Tizen.Core/Tizen.Core/ChannelSender.cs

@@ -19,7 +19,7 @@
 namespace Tizen.Core
 {
     /// <summary>
-    /// Represents the channel sender used for inter-task communication.
+    /// Represents the channel sender used for inter-task communication. It provides methods to send messages between tasks in order to facilitate task coordination.
     /// </summary>
     /// <since_tizen> 12 </since_tizen>
     public class ChannelSender : IDisposable
@@ -32,7 +32,7 @@ internal ChannelSender(IntPtr handle)
         }
 
         /// <summary>
-        /// Finalizer of the class ChannelSender.
+        /// Finalizes an instance of the ChannelSender class.
         /// </summary>
         ~ChannelSender()
         {

src/Tizen.Core/Tizen.Core/Event.cs

@@ -19,8 +19,13 @@
 namespace Tizen.Core
 {
     /// <summary>
-    /// Represents the event using for broadcasting events.
+    /// Represents the event used for broadcasting events.
     /// </summary>
+    /// <remarks>
+    /// This class provides functionality for managing events that are broadcasted across multiple components in an application.
+    /// It enables communication between different parts of the code without resorting to direct references or global variables.
+    /// By implementing the IDisposable interface, it ensures proper resource management and prevents memory leaks.
+    /// </remarks>
     /// <since_tizen> 12 </since_tizen>
 #pragma warning disable CA1716
     public class Event : IDisposable
@@ -33,13 +38,16 @@ public class Event : IDisposable
         /// <summary>
         /// Constructor for creating a new event instance.
         /// </summary>
+        /// <remarks>
+        /// This constructor initializes a new event instance. It may throw exceptions if there are any issues during initialization such as running out of memory or performing an invalid operation.
+        /// </remarks>
         /// <exception cref="OutOfMemoryException">Thrown when out of memory.</exception>
         /// <exception cref="InvalidOperationException">Thrown when failed because of an invalid operation.</exception>
         /// <example>
+        /// Here's an example showing how to create a new event instance:
         /// <code>
-        /// 
+        /// Create a new event instance
         /// var coreEvent = new Event();
-        /// 
         /// </code>
         /// </example>
         /// <since_tizen> 12 </since_tizen>
@@ -57,7 +65,7 @@ public Event()
         }
 
         /// <summary>
-        /// Finalizer of the class Event.
+        /// Finalizes an instance of the Event class.
         /// </summary>
         ~Event()
         {

src/Tizen.Core/Tizen.Core/EventObject.cs

@@ -70,7 +70,7 @@ internal EventObject(IntPtr handle)
         }
 
         /// <summary>
-        /// Finalizer of the class EventObject.
+        /// Finalizes an instance of the EventObject class.
         /// </summary>
         ~EventObject()
         {

src/Tizen.Core/Tizen.Core/EventReceivedEventArgs.cs

@@ -19,7 +19,7 @@
 namespace Tizen.Core
 {
     /// <summary>
-    /// Arguments for the event raised when the event data is received.
+    /// Represents the arguments passed to the event handler when the event data is received.
     /// </summary>
     /// <since_tizen> 12 </since_tizen>
     public class EventReceivedEventArgs : System.EventArgs

src/Tizen.Core/Tizen.Core/Task.cs

@@ -43,16 +43,16 @@ public class Task : IDisposable
         private static int _id = 1;
 
         /// <summary>
-        /// Initializes the Task class.
+        /// Initializes the Task class with the specified ID.
         /// </summary>
-        /// <param name="id">The ID of the task.</param>
+        /// <param name="id">The unique identifier for the task.</param>
         /// <exception cref="ArgumentException">Thrown when the <paramref name="id"/> is invalid or a Task with that ID already exists.</exception>
         /// <exception cref="OutOfMemoryException">Thrown when out of memory.</exception>
         /// <exception cref="InvalidOperationException">Thrown when failed because of an invalid operation.</exception>
         /// <remarks>
-        /// The constructor throws an exception when the id already exists.
-        /// By default, the task creates a thread. However, if the <paramref name="id"/> is "main", a thread is not created.
-        /// The 'main' task will be operated in the main thread.
+        /// The constructor throws an exception when the ID already exists.
+        /// By default, the task creates a separate thread. However, if the <paramref name="id"/> is set to "main", no separate thread is created.
+        /// In such case, the 'main' task will operate on the main application thread instead.
         /// </remarks>
         /// <example>
         /// <code>
@@ -87,7 +87,6 @@ internal Task(IntPtr handle)
              Dispose(false);
         }
 
-
         /// <summary>
         /// Posts an action to be executed later.
         /// </summary>
@@ -283,12 +282,14 @@ public void RemoveTimer(int id)
         /// <summary>
         /// Adds a channel receiver to a main loop of the task.
         /// </summary>
-        /// <param name="receiver">The channel receiver instance.</param>
+        /// <param name="receiver">The channel receiver instance that needs to be added.</param>
         /// <exception cref="ArgumentNullException">Thrown when the argument is null.</exception>
         /// <exception cref="ArgumentException">Thrown when the argument is invalid.</exception>
         /// <exception cref="InvalidOperationException">Thrown when failed because of an invalid operation.</exception>
         /// <exception cref="OutOfMemoryException">Thrown when out of memory.</exception>
         /// <example>
+        /// In the following code snippet, we create a channel, find or spawn a task named "ReceivingTask", and then add the channel receiver to the task's main loop by calling the 'AddChannelReceiver' method.
+        ///
         /// <code>
         /// 
         /// var channel = new Channel();
@@ -514,7 +515,7 @@ public void RemoveEvent(Event coreEvent)
         /// Emits the event object to all registered event handlers of the task. 
         /// It's similar to Event.Emit(), but EmitAllEvent() sends the event object to every event handler of the task while Event.Emit() sends the event object only to the target event's event handler.
         /// </summary>
-        /// <param name="eventObject">The event object instance.</param>
+        /// <param name="eventObject">The event object instance to be sent.</param>
         /// <exception cref="ArgumentNullException">Thrown when the argument is null.</exception>
         /// <exception cref="ArgumentException">Thrown when the argument is invalid.</exception>
         /// <exception cref="InvalidOperationException">Thrown when failed because of an invalid operation.</exception>
@@ -675,11 +676,13 @@ public bool Running {
         /// </summary>
         /// <exception cref="InvalidOperationException">Thrown when failed because of an invalid operation.</exception>
         /// <example>
+        /// Here's an example that demonstrates how to create a Core Task and run its main loop:
         /// <code>
-        /// 
+        /// // Create a Core Task named "Runner"
         /// var coreTask = new TCoreTask("Runner");
-        /// coreTask.Run();
         /// 
+        /// // Start the main loop of the task
+        /// coreTask.Run();
         /// </code>
         /// </example>
         /// <since_tizen> 12 </since_tizen>