[AudioManager] Improve documentation (#6352)

Signed-off-by: Jaechul Lee <[email protected]>

src/Tizen.Multimedia/AudioManager/AudioDevice.cs

@@ -23,7 +23,11 @@
 namespace Tizen.Multimedia
 {
     /// <summary>
-    /// Provides the ability to query the information of sound devices.
+    /// Represents an audio device in the system, providing functionality to query and manipulate its properties.
+    /// The <see cref="AudioDevice"/> class allows developers to interact with audio devices by retrieving
+    /// detailed information such as the device's ID, name, type, I/O direction, and its current running state.
+    /// Furthermore, it provides methods for getting and setting sample formats and rates, managing resampling options,
+    /// and restricting stream types to media-only, facilitating optimized audio handling for diverse applications.
     /// </summary>
     /// <since_tizen> 3 </since_tizen>
     public class AudioDevice
@@ -51,35 +55,47 @@ internal AudioDevice(IntPtr deviceHandle)
         }
 
         /// <summary>
-        /// Gets the ID of the device.
+        /// Gets the unique identifier of the audio device.
+        /// This ID serves as a reference to identify the device within the system and
+        /// is crucial for performing operations on specific devices.
         /// </summary>
         /// <value>The id of the device.</value>
         /// <since_tizen> 3 </since_tizen>
         public int Id => _id;
 
         /// <summary>
-        /// Gets the name of the device.
+        /// Gets the name of the audio device.
+        /// This property provides a human-readable identifier for the device,
+        /// which can be used in user interfaces or logs to display information
+        /// about the current audio output/input device.
         /// </summary>
         /// <value>The name of the device.</value>
         /// <since_tizen> 3 </since_tizen>
         public string Name { get; }
 
         /// <summary>
-        /// Gets the type of the device.
+        /// Gets the type of the audio device.
+        /// This property returns an enumerated value of type <see cref="AudioDeviceType"/>
+        /// that indicates the specific category of the device, such as speakers, microphones,
+        /// or headphones, which helps in distinguishing between different device functionalities.
         /// </summary>
         /// <value>The <see cref="AudioDeviceType"/> of the device.</value>
         /// <since_tizen> 3 </since_tizen>
         public AudioDeviceType Type => _type;
 
         /// <summary>
-        /// Gets the IO direction of the device.
+        /// Gets the input/output (I/O) direction of the audio device.
+        /// This property indicates whether the device is designed for input (recording) or output (playback),
+        /// allowing developers to manage device usage appropriately in their applications.
         /// </summary>
         /// <value>The IO direction of the device.</value>
         /// <since_tizen> 3 </since_tizen>
         public AudioDeviceIoDirection IoDirection => _ioDirection;
 
         /// <summary>
-        /// Gets the running state of the device.
+        /// Gets a value indicating whether the audio device is currently running.
+        /// This property checks the operational state of the device and returns <c>true</c>
+        /// if the device is active and processing audio, or <c>false</c> if it is idle or inactive.
         /// </summary>
         /// <value>true if the audio stream of device is running actually; otherwise, false.</value>
         /// <since_tizen> 5 </since_tizen>
@@ -95,7 +111,10 @@ public bool IsRunning
         }
 
         /// <summary>
-        /// Gets the device's supported sample formats.
+        /// Retrieves a collection of audio sample formats supported by the device.
+        /// This method returns an enumerable list of <see cref="AudioSampleFormat"/> values
+        /// indicating the different audio formats the device can handle, enabling applications
+        /// to select a compatible format for audio processing.
         /// </summary>
         /// <returns>An IEnumerable&lt;AudioSampleFormat&gt; that contains supported sample formats.</returns>
         /// <remarks>
@@ -127,7 +146,9 @@ IEnumerable<AudioSampleFormat> RetrieveFormats()
         }
 
         /// <summary>
-        /// Sets the device's sample format.
+        /// Sets the sample format for the audio device.
+        /// This method allows developers to specify a desired <see cref="AudioSampleFormat"/> for
+        /// audio playback or recording.
         /// </summary>
         /// <param name="format">The <see cref="AudioSampleFormat"/> to set to the device.</param>
         /// <remarks>
@@ -142,7 +163,9 @@ public void SetSampleFormat(AudioSampleFormat format)
         }
 
         /// <summary>
-        /// Gets the device's sample format.
+        /// Gets the current sample format used by the audio device.
+        /// This method retrieves the current <see cref="AudioSampleFormat"/> the device is operating with,
+        /// allowing applications to verify or adjust to the active format being utilized for audio streams.
         /// </summary>
         /// <returns>The <see cref="AudioSampleFormat"/> of the device.</returns>
         /// <remarks>
@@ -195,7 +218,9 @@ private uint ConvertRateToCoreValue(uint rate)
         }
 
         /// <summary>
-        /// Gets the device's supported sample rates.
+        /// Retrieves the sample rates that the audio device supports.
+        /// This method returns an enumerable list of supported sample rates, allowing developers
+        /// to select an appropriate rate for audio processing based on the capabilities of the device.
         /// </summary>
         /// <returns>An IEnumerable&lt;uint&gt; that contains supported sample rates.</returns>
         /// <remarks>
@@ -229,7 +254,10 @@ IEnumerable<uint> RetrieveRates()
         }
 
         /// <summary>
-        /// Sets the device's sample rate.
+        /// Sets the sample rate for the audio device.
+        /// This method allows you to specify a desired sample rate (in Hz) for audio playback or recording.
+        /// Choosing an appropriate sample rate is important for maintaining audio quality and ensuring compatibility
+        /// with audio data formats.
         /// </summary>
         /// <param name="rate">The sample rate to set to the device.</param>
         /// <remarks>
@@ -244,7 +272,9 @@ public void SetSampleRate(uint rate)
         }
 
         /// <summary>
-        /// Gets the device's sample rate.
+        /// Gets the current sample rate of the audio device.
+        /// This method retrieves the sample rate currently in use for audio processing, allowing
+        /// applications to ensure they are operating with the correct audio quality settings.
         /// </summary>
         /// <returns>The sample rate of the device.</returns>
         /// <remarks>
@@ -261,7 +291,10 @@ public uint GetSampleRate()
         }
 
         /// <summary>
-        /// Sets the device's 'avoid resampling' property.
+        /// Sets the 'avoid resampling' property for the audio device.
+        /// This property controls whether the device should avoid resampling audio data during playback.
+        /// Enabling this feature can help preserve audio quality by preventing alterations to audio that
+        /// may happen during playback.
         /// </summary>
         /// <param name="enable">The 'avoid resampling' value to set to the device.</param>
         /// <remarks>
@@ -279,7 +312,9 @@ public void SetAvoidResampling(bool enable)
         }
 
         /// <summary>
-        /// Gets the device's 'avoid resampling' property.
+        /// Gets the current state of the 'avoid resampling' property for the audio device.
+        /// This method returns whether the device is currently configured to avoid resampling audio data,
+        /// allowing developers to assess the current settings related to audio processing quality.
         /// </summary>
         /// <returns>The 'avoid resampling' property of the device.</returns>
         /// <remarks>
@@ -298,7 +333,10 @@ public bool GetAvoidResampling()
         }
 
         /// <summary>
-        /// Sets the restriction of stream type only for media.
+        /// Sets a restriction on the audio device to allow only media streams.
+        /// This method configures the device to accept only audio streams of type
+        /// <see cref="AudioStreamType.Media"/>. When enabled, the device will reject
+        /// any other stream types, ensuring that it is exclusively used for media playback.
         /// </summary>
         /// <param name="enable">The 'media stream only' value to set to the device.</param>
         /// <remarks>
@@ -315,7 +353,9 @@ public void SetMediaStreamOnly(bool enable)
         }
 
         /// <summary>
-        /// Gets the restriction of stream type only for media.
+        /// Retrieves the current restriction status of the audio device regarding media streams.
+        /// This method checks whether the device is currently configured to accept only media streams,
+        /// returning a boolean value that indicates the state of the restriction.
         /// </summary>
         /// <returns>The 'media stream only' property of the device.</returns>
         /// <remarks>
@@ -334,15 +374,21 @@ public bool GetMediaStreamOnly()
         }
 
         /// <summary>
-        /// Returns a string that represents the current object.
+        /// Returns a string representation of the current instance.
+        /// This method provides a formatted string that includes key properties of the audio device,
+        /// such as its unique identifier, name, type, I/O direction, and running state.
+        /// This representation can be useful for logging, debugging, or displaying device information
+        /// in user interfaces.
         /// </summary>
         /// <returns>A string that represents the current object.</returns>
         /// <since_tizen> 4 </since_tizen>
         public override string ToString() =>
             $"Id={Id}, Name={Name}, Type={Type}, IoDirection={IoDirection}, IsRunning={IsRunning}";
 
         /// <summary>
-        /// Compares an object to an instance of <see cref="AudioDevice"/> for equality.
+        /// Compares the current instance of <see cref="AudioDevice"/> with another object for equality.
+        /// This method checks if the specified object is an instance of <see cref="AudioDevice"/>
+        /// and compares their unique identifiers to determine if they represent the same audio device.
         /// </summary>
         /// <param name="obj">A <see cref="Object"/> to compare.</param>
         /// <returns>true if the two devices are equal; otherwise, false.</returns>
@@ -359,7 +405,10 @@ public override bool Equals(object obj)
         }
 
         /// <summary>
-        /// Gets the hash code for this instance of <see cref="AudioDevice"/>.
+        /// Retrieves the hash code for the current instance of <see cref="AudioDevice"/>.
+        /// This method generates a hash code based on the unique identifier of the audio device,
+        /// which can be useful for storing instances in hash-based collections such as dictionaries
+        /// or hash sets.
         /// </summary>
         /// <returns>The hash code for this instance of <see cref="AudioDevice"/>.</returns>
         /// <since_tizen> 4 </since_tizen>

src/Tizen.Multimedia/AudioManager/AudioDeviceConnectionChangedEventArgs.cs

@@ -20,6 +20,12 @@ namespace Tizen.Multimedia
 {
     /// <summary>
     /// Provides data for the <see cref="AudioManager.DeviceConnectionChanged"/> event.
+    /// This event is triggered when there is a change in the connection status of an audio device,
+    /// such as when a device is connected or disconnected from the system.
+    /// The <see cref="AudioDeviceConnectionChangedEventArgs"/> class encapsulates information
+    /// about the device involved in the connection change and its current connection state,
+    /// allowing developers to easily respond to changes in the audio subsystem and update
+    /// application behavior accordingly.
     /// </summary>
     /// <since_tizen> 3 </since_tizen>
     public class AudioDeviceConnectionChangedEventArgs : EventArgs
@@ -31,14 +37,23 @@ internal AudioDeviceConnectionChangedEventArgs(AudioDevice device, bool isConnec
         }
 
         /// <summary>
-        /// Gets the device.
+        /// Gets the device that is involved in the connection change.
+        /// This property returns an instance of <see cref="AudioDevice"/>, which represents
+        /// the specific audio device that has been connected or disconnected.
+        /// This information is essential for applications that need to manage multiple audio devices,
+        /// allowing them to identify the affected device and adjust their functionality accordingly.
         /// </summary>
         /// <value>The <see cref="AudioDevice"/>.</value>
         /// <since_tizen> 3 </since_tizen>
         public AudioDevice Device { get; }
 
         /// <summary>
-        /// Gets the connection state of the device.
+        /// Gets the current connection state of the device.
+        /// This property indicates whether the audio device is currently connected to the system.
+        /// It will return <c>true</c> if the device is connected and <c>false</c> if it has
+        /// been disconnected. This information is crucial for determining the audio routing and
+        /// playback options, enabling applications to appropriately react to the presence
+        /// or absence of audio devices in the environment.
         /// </summary>
         /// <value>true if the device is connected; otherwise, false.</value>
         /// <since_tizen> 3 </since_tizen>

src/Tizen.Multimedia/AudioManager/AudioDeviceIoDirection.cs

@@ -17,7 +17,9 @@
 namespace Tizen.Multimedia
 {
     /// <summary>
-    /// Specifies the audio device directions.
+    /// Defines the data flow directions for audio devices, indicating whether
+    /// a device is for input, output, or both. This helps in managing audio
+    /// interactions within applications effectively.
     /// </summary>
     /// <since_tizen> 3 </since_tizen>
     public enum AudioDeviceIoDirection

src/Tizen.Multimedia/AudioManager/AudioDeviceRunningChangedEventArgs.cs

@@ -19,7 +19,11 @@
 namespace Tizen.Multimedia
 {
     /// <summary>
-    /// Provides data for the <see cref="AudioManager.DeviceRunningChanged"/> event.
+    /// Provides the data for the <see cref="AudioManager.DeviceRunningChanged"/> event,
+    /// which is triggered when the running state of an audio device changes.
+    /// This class encapsulates information about the specific audio device
+    /// that has undergone a state change, as well as its current running status,
+    /// allowing subscribers to respond appropriately to changes in audio device activity.
     /// </summary>
     /// <since_tizen> 5 </since_tizen>
     public class AudioDeviceRunningChangedEventArgs : EventArgs
@@ -44,4 +48,4 @@ internal AudioDeviceRunningChangedEventArgs(AudioDevice device, bool isRunning)
         /// <since_tizen> 5 </since_tizen>
         public bool IsRunning { get; }
     }
-}
+}

src/Tizen.Multimedia/AudioManager/AudioDeviceType.cs

@@ -17,58 +17,75 @@
 namespace Tizen.Multimedia
 {
     /// <summary>
-    /// Specifies the audio device types.
+    /// Represents the various types of audio devices available in the system.
+    /// This enumeration categorizes audio devices based on their functionality and
+    /// connection type, enabling developers to easily identify and utilize
+    /// the appropriate audio device for their applications. The types include
+    /// built-in speakers and microphones, external connections like audio jacks,
+    /// Bluetooth, HDMI, USB audio, and network audio devices, facilitating
+    /// effective audio management in diverse scenarios.
     /// </summary>
     /// <since_tizen> 3 </since_tizen>
     public enum AudioDeviceType
     {
         /// <summary>
-        /// Built-in speaker.
+        /// Represents the built-in speaker of the device, typically used for
+        /// playback of audio through the device's internal audio output.
         /// </summary>
         BuiltinSpeaker,
 
         /// <summary>
-        /// Built-in receiver.
+        /// Represents the built-in receiver, usually utilized for phone calls
+        /// and communication through the device, providing audio input and output.
         /// </summary>
         BuiltinReceiver,
 
         /// <summary>
-        /// Built-in microphone.
+        /// Represents the built-in microphone, used for capturing audio input
+        /// from the environment, such as for voice commands, calls, or recordings.
         /// </summary>
         BuiltinMic,
 
         /// <summary>
-        /// Audio jack that can be connected to wired accessories such as headphones and headsets.
+        /// Indicates an audio jack that allows the connection of wired accessories
+        /// such as headphones and headsets, providing a physical interface for
+        /// audio playback and recording.
         /// </summary>
         AudioJack,
 
         /// <summary>
-        /// Bluetooth media (A2DP).
+        /// Represents Bluetooth media devices using the A2DP (Advanced Audio
+        /// Distribution Profile) standard for streaming high-quality audio wirelessly.
         /// </summary>
         BluetoothMedia,
 
         /// <summary>
-        /// HDMI.
+        /// Represents HDMI audio output, allowing the transmission of high-fidelity
+        /// audio and video to external displays or audio receivers through an HDMI cable.
         /// </summary>
         Hdmi,
 
         /// <summary>
-        /// Device for forwarding.
+        /// Represents devices used for forwarding audio data, which may involve
+        /// relaying audio signals to other devices or systems for processing or playback.
         /// </summary>
         Forwarding,
 
         /// <summary>
-        /// USB audio.
+        /// Represents USB audio devices, which connect through USB ports to provide
+        /// audio input and output, such as external sound cards or USB microphones.
         /// </summary>
         UsbAudio,
 
         /// <summary>
-        /// Bluetooth voice (SCO).
+        /// Represents Bluetooth voice devices using the SCO (Synchronous Connection
+        /// Oriented) profile, primarily used for voice communication over Bluetooth.
         /// </summary>
         BluetoothVoice,
 
         /// <summary>
-        /// Device for the transmission of audio data over a network
+        /// Represents devices that transmit audio data over a network, enabling audio
+        /// streaming or communication over internet or local networks.
         /// </summary>
         Network
     }