From 2ece14bed70400a4f9d502e5d207689ce65b8615 Mon Sep 17 00:00:00 2001 From: hjhun <36876573+hjhun@users.noreply.github.com> Date: Mon, 30 Sep 2024 09:44:45 +0900 Subject: [PATCH] [Tizen.Core] Enhance API descriptions (#6378) * [Tizen.Core] Enhance API descriptions Signed-off-by: Hwankyu Jhun * [Tizen.Core] Add a missing '/' Signed-off-by: Hwankyu Jhun --------- Signed-off-by: Hwankyu Jhun --- src/Tizen.Core/Tizen.Core/Channel.cs | 34 +++++++++++++++---- src/Tizen.Core/Tizen.Core/ChannelObject.cs | 14 ++++++-- .../Tizen.Core/ChannelReceivedEventArgs.cs | 2 +- src/Tizen.Core/Tizen.Core/ChannelReceiver.cs | 20 ++++++----- src/Tizen.Core/Tizen.Core/ChannelSender.cs | 4 +-- src/Tizen.Core/Tizen.Core/Event.cs | 16 ++++++--- src/Tizen.Core/Tizen.Core/EventObject.cs | 2 +- .../Tizen.Core/EventReceivedEventArgs.cs | 2 +- src/Tizen.Core/Tizen.Core/Task.cs | 23 +++++++------ 9 files changed, 81 insertions(+), 36 deletions(-) diff --git a/src/Tizen.Core/Tizen.Core/Channel.cs b/src/Tizen.Core/Tizen.Core/Channel.cs index 0079e83e7e7..e1727a642cf 100644 --- a/src/Tizen.Core/Tizen.Core/Channel.cs +++ b/src/Tizen.Core/Tizen.Core/Channel.cs @@ -21,28 +21,39 @@ namespace Tizen.Core /// /// The class for managing communication channels between tasks of Tizen Core. /// + /// + /// 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. + /// /// 12 public class Channel : IDisposable { private bool _disposed = false; /// - /// Constructor for creating a new channel with a sender and a receiver. + /// Creates a new channel with a sender and a receiver. /// + /// + /// 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. + /// /// Thrown when out of memory. /// Thrown when failed because of an invalid operation. /// + /// 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. /// - /// /// try /// { - /// var channel = new Channel(); + /// var channel = new Channel(); /// } /// catch (OutOfMemoryException) /// { - /// Console.WriteLine("Exception occurs"); + /// Console.WriteLine("Exception occurs"); /// } - /// /// /// /// 12 @@ -55,7 +66,7 @@ public Channel() } /// - /// Finalizer of the class Channel. + /// Finalizes an instance of the Channel class. /// ~Channel() { @@ -65,12 +76,21 @@ public Channel() /// /// Gets the channel sender instance. /// + /// + /// 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. + /// /// 12 public ChannelSender Sender { get; private set; } /// - /// Gets the channel receiver instance. + /// Gets the channel receiver instance. /// + /// + /// 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. + /// /// 12 public ChannelReceiver Receiver { get; private set; } diff --git a/src/Tizen.Core/Tizen.Core/ChannelObject.cs b/src/Tizen.Core/Tizen.Core/ChannelObject.cs index a721c60018b..eff18ba1fb7 100644 --- a/src/Tizen.Core/Tizen.Core/ChannelObject.cs +++ b/src/Tizen.Core/Tizen.Core/ChannelObject.cs @@ -24,6 +24,11 @@ namespace Tizen.Core /// /// Represents a channel object used for inter-task communication. /// + /// + /// 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. + /// /// 12 public class ChannelObject : IDisposable { @@ -40,6 +45,10 @@ public class ChannelObject : IDisposable /// The data object. /// Thrown when out of memory. /// Thrown when failed because of an invalid operation. + /// + /// 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. + /// /// /// /// @@ -68,7 +77,7 @@ internal ChannelObject(IntPtr handle) } /// - /// Finalizer of the class ChannelObject. + /// Finalizes an instance of the ChannelObject class. /// ~ChannelObject() { @@ -135,7 +144,8 @@ public object Data /// Gets the name of the sender task. /// /// 12 - public string Sender { + public string Sender + { get { Interop.LibTizenCore.TizenCoreChannel.ObjectGetSenderTaskName(_handle, out IntPtr taskName); diff --git a/src/Tizen.Core/Tizen.Core/ChannelReceivedEventArgs.cs b/src/Tizen.Core/Tizen.Core/ChannelReceivedEventArgs.cs index 4c5fdf13eb4..64bf33459ef 100644 --- a/src/Tizen.Core/Tizen.Core/ChannelReceivedEventArgs.cs +++ b/src/Tizen.Core/Tizen.Core/ChannelReceivedEventArgs.cs @@ -19,7 +19,7 @@ namespace Tizen.Core { /// - /// 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. /// /// 12 public class ChannelReceivedEventArgs : System.EventArgs diff --git a/src/Tizen.Core/Tizen.Core/ChannelReceiver.cs b/src/Tizen.Core/Tizen.Core/ChannelReceiver.cs index c1c62d435be..0c6ae5c6b1b 100644 --- a/src/Tizen.Core/Tizen.Core/ChannelReceiver.cs +++ b/src/Tizen.Core/Tizen.Core/ChannelReceiver.cs @@ -35,7 +35,7 @@ internal ChannelReceiver(IntPtr handle) } /// - /// Finalizer of the class ChannelReceiver. + /// Finalizes an instance of the ChannelReceiver class. /// ~ChannelReceiver() { @@ -43,7 +43,7 @@ internal ChannelReceiver(IntPtr handle) } /// - /// 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. /// /// /// 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); /// }; /// /// @@ -63,19 +63,23 @@ internal ChannelReceiver(IntPtr handle) public event EventHandler Received; /// - /// Receives the channel object from the sender asynchronously. + /// Asynchronously receives the channel object from the sender. /// /// The received channel object. /// Thrown when out of memory. - /// Thrown when failed because of an invalid operation. + /// Thrown when failed due to an invalid operation. /// /// /// /// 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()); + /// } /// }); /// /// diff --git a/src/Tizen.Core/Tizen.Core/ChannelSender.cs b/src/Tizen.Core/Tizen.Core/ChannelSender.cs index ae170bac46d..1156d9ec49e 100644 --- a/src/Tizen.Core/Tizen.Core/ChannelSender.cs +++ b/src/Tizen.Core/Tizen.Core/ChannelSender.cs @@ -19,7 +19,7 @@ namespace Tizen.Core { /// - /// 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. /// /// 12 public class ChannelSender : IDisposable @@ -32,7 +32,7 @@ internal ChannelSender(IntPtr handle) } /// - /// Finalizer of the class ChannelSender. + /// Finalizes an instance of the ChannelSender class. /// ~ChannelSender() { diff --git a/src/Tizen.Core/Tizen.Core/Event.cs b/src/Tizen.Core/Tizen.Core/Event.cs index 21755d97df4..f705845e561 100644 --- a/src/Tizen.Core/Tizen.Core/Event.cs +++ b/src/Tizen.Core/Tizen.Core/Event.cs @@ -19,8 +19,13 @@ namespace Tizen.Core { /// - /// Represents the event using for broadcasting events. + /// Represents the event used for broadcasting events. /// + /// + /// 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. + /// /// 12 #pragma warning disable CA1716 public class Event : IDisposable @@ -33,13 +38,16 @@ public class Event : IDisposable /// /// Constructor for creating a new event instance. /// + /// + /// 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. + /// /// Thrown when out of memory. /// Thrown when failed because of an invalid operation. /// + /// Here's an example showing how to create a new event instance: /// - /// + /// Create a new event instance /// var coreEvent = new Event(); - /// /// /// /// 12 @@ -57,7 +65,7 @@ public Event() } /// - /// Finalizer of the class Event. + /// Finalizes an instance of the Event class. /// ~Event() { diff --git a/src/Tizen.Core/Tizen.Core/EventObject.cs b/src/Tizen.Core/Tizen.Core/EventObject.cs index 9012bc9094a..22d2ff5af07 100644 --- a/src/Tizen.Core/Tizen.Core/EventObject.cs +++ b/src/Tizen.Core/Tizen.Core/EventObject.cs @@ -70,7 +70,7 @@ internal EventObject(IntPtr handle) } /// - /// Finalizer of the class EventObject. + /// Finalizes an instance of the EventObject class. /// ~EventObject() { diff --git a/src/Tizen.Core/Tizen.Core/EventReceivedEventArgs.cs b/src/Tizen.Core/Tizen.Core/EventReceivedEventArgs.cs index fb561bbd686..93d91914d81 100644 --- a/src/Tizen.Core/Tizen.Core/EventReceivedEventArgs.cs +++ b/src/Tizen.Core/Tizen.Core/EventReceivedEventArgs.cs @@ -19,7 +19,7 @@ namespace Tizen.Core { /// - /// 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. /// /// 12 public class EventReceivedEventArgs : System.EventArgs diff --git a/src/Tizen.Core/Tizen.Core/Task.cs b/src/Tizen.Core/Tizen.Core/Task.cs index 4ca4cc81dd4..a6796b368fb 100644 --- a/src/Tizen.Core/Tizen.Core/Task.cs +++ b/src/Tizen.Core/Tizen.Core/Task.cs @@ -43,16 +43,16 @@ public class Task : IDisposable private static int _id = 1; /// - /// Initializes the Task class. + /// Initializes the Task class with the specified ID. /// - /// The ID of the task. + /// The unique identifier for the task. /// Thrown when the is invalid or a Task with that ID already exists. /// Thrown when out of memory. /// Thrown when failed because of an invalid operation. /// - /// The constructor throws an exception when the id already exists. - /// By default, the task creates a thread. However, if the 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 is set to "main", no separate thread is created. + /// In such case, the 'main' task will operate on the main application thread instead. /// /// /// @@ -87,7 +87,6 @@ internal Task(IntPtr handle) Dispose(false); } - /// /// Posts an action to be executed later. /// @@ -283,12 +282,14 @@ public void RemoveTimer(int id) /// /// Adds a channel receiver to a main loop of the task. /// - /// The channel receiver instance. + /// The channel receiver instance that needs to be added. /// Thrown when the argument is null. /// Thrown when the argument is invalid. /// Thrown when failed because of an invalid operation. /// Thrown when out of memory. /// + /// 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. + /// /// /// /// 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. /// - /// The event object instance. + /// The event object instance to be sent. /// Thrown when the argument is null. /// Thrown when the argument is invalid. /// Thrown when failed because of an invalid operation. @@ -675,11 +676,13 @@ public bool Running { /// /// Thrown when failed because of an invalid operation. /// + /// Here's an example that demonstrates how to create a Core Task and run its main loop: /// - /// + /// // Create a Core Task named "Runner" /// var coreTask = new TCoreTask("Runner"); - /// coreTask.Run(); /// + /// // Start the main loop of the task + /// coreTask.Run(); /// /// /// 12