[MediaPlayer] Improve documentation (#6357)

* [MediaPlayer] Improve documentation

src/Tizen.Multimedia.MediaPlayer/Player/AdaptiveVariants.cs

@@ -93,7 +93,7 @@ internal AdaptiveVariants(Player player)
         }
 
         /// <summary>
-        /// Sets the maximum limit of the streaming variant.
+        /// Sets the maximum limit of adaptive streaming variants.
         /// </summary>
         /// <exception cref="ObjectDisposedException">The <see cref="Player"/> has already been disposed of.</exception>
         /// <exception cref="ArgumentOutOfRangeException">
@@ -119,7 +119,7 @@ public void SetMaxLimit(int bandwidth, int width = -1, int height = -1)
         }
 
         /// <summary>
-        /// Gets the maximum limit of the streaming variant.
+        /// Gets the maximum limit of the adaptive streaming variant.
         /// </summary>
         /// <returns>The <see cref="VariantInfo"/> containing the variant information.</returns>
         /// <exception cref="ObjectDisposedException">The <see cref="Player"/> has already been disposed of.</exception>
@@ -136,7 +136,7 @@ public VariantInfo GetMaxLimit()
         }
 
         /// <summary>
-        /// Retrieves all the available adaptive variants.
+        /// Retrieves all the available adaptive streaming variants.
         /// </summary>
         /// <returns>
         /// It returns a list contained all the available adaptive variants.

src/Tizen.Multimedia.MediaPlayer/Player/AudioDataDecodedEventArgs.cs

@@ -32,7 +32,7 @@ internal AudioDataDecodedEventArgs(MediaPacket packet)
         }
 
         /// <summary>
-        /// Gets the packet containing the decoded frame.
+        /// Gets the media packet containing the audio decoded frame.
         /// </summary>
         /// <since_tizen> 6 </since_tizen>
         public MediaPacket Packet { get; }

src/Tizen.Multimedia.MediaPlayer/Player/AudioEffect.cs

@@ -98,7 +98,7 @@ public void Clear()
         }
 
         /// <summary>
-        /// Gets the number of items.
+        /// Gets the number of equalizer bands available.
         /// </summary>
         /// <exception cref="NotAvailableException">If audio offload is enabled by calling <see cref="AudioOffload.IsEnabled"/>. (Since tizen 6.0)
         ///     -or-<br/>
@@ -148,7 +148,7 @@ public Range BandLevelRange
         }
 
         /// <summary>
-        /// Gets the value whether the AudioEffect is available or not.
+        /// Gets the value indicating whether the AudioEffect is available or not.
         /// </summary>
         /// <remarks>This function returns the availability of the <see cref="AudioEffect"/>.
         /// It could be unavailable depending on the platform capabilities.<br/>

src/Tizen.Multimedia.MediaPlayer/Player/AudioOffload.cs

@@ -50,7 +50,7 @@ internal void CheckDisabled()
         }
 
         /// <summary>
-        /// Enables or disables the audio offload.
+        /// Gets or sets whether the audio offload is enabled.
         /// </summary>
         /// <value>The value indicating whether or not audio offload is enabled. The default value is false.</value>
         /// <remarks><para>The player lets the hardware decode and render the sound if the audio offload is enabled.
@@ -103,7 +103,7 @@ public bool IsEnabled
         }
 
         /// <summary>
-        /// Get a state whether or not the audio offload is activated.
+        /// Get a value indication whether or not the audio offload is activated.
         /// </summary>
         /// <value>The value indicating whether or not AudioOffload is activated.</value>
         /// <remarks>

src/Tizen.Multimedia.MediaPlayer/Player/EqualizerBand.cs

@@ -85,7 +85,7 @@ public int Level
 
 
         /// <summary>
-        /// Gets the frequency in dB.
+        /// Gets the frequency in dB of the equalizer band.
         /// </summary>
         /// <exception cref="NotAvailableException">
         ///     If audio offload is enabled by calling <see cref="AudioOffload.IsEnabled"/>. (Since tizen 6.0)
@@ -105,7 +105,7 @@ public int Frequency
         }
 
         /// <summary>
-        /// Gets the frequency range in dB.
+        /// Gets the frequency range in dB of the equalizer band.
         /// </summary>
         /// <exception cref="NotAvailableException">
         ///     If audio offload is enabled by calling <see cref="AudioOffload.IsEnabled"/>. (Since tizen 6.0)

src/Tizen.Multimedia.MediaPlayer/Player/MediaBufferSource.cs

@@ -33,7 +33,7 @@ public sealed class MediaBufferSource : MediaSource
         private byte[] _buffer;
 
         /// <summary>
-        /// Initializes a new instance of the MediaBufferSource class with an allocated buffer.
+        /// Initializes a new instance of the MediaBufferSource class with the specified buffer length.
         /// </summary>
         /// <param name="length">The value indicating the size of the buffer.</param>
         /// <exception cref="ArgumentOutOfRangeException">
@@ -54,7 +54,7 @@ public MediaBufferSource(int length)
         }
 
         /// <summary>
-        /// Initializes a new instance of the MediaBufferSource class from the buffer.
+        /// Initializes a new instance of the MediaBufferSource class with the specified buffer.
         /// </summary>
         /// <param name="buffer">The source array to be copied into the buffer.</param>
         /// <exception cref="ArgumentNullException"><paramref name="buffer"/> is null.</exception>
@@ -65,7 +65,7 @@ public MediaBufferSource(byte[] buffer) : this(buffer, buffer == null ? 0 : buff
 
         //TODO remove default parameter.
         /// <summary>
-        /// Initializes a new instance of the MediaBufferSource class from the buffer
+        /// Initializes a new instance of the MediaBufferSource class with buffer, length, and optional offset.
         /// with the specified length and the specified offset.
         /// </summary>
         /// <param name="buffer">The source array to be copied into the buffer.</param>
@@ -141,4 +141,3 @@ internal override void OnAttached(Player player)
         }
     }
 }
-

src/Tizen.Multimedia.MediaPlayer/Player/MediaStreamBufferStatusChangedEventArgs.cs

@@ -36,7 +36,7 @@ public MediaStreamBufferStatusChangedEventArgs(MediaStreamBufferStatus status)
         }
 
         /// <summary>
-        /// Gets the status.
+        /// Gets the current buffer status.
         /// </summary>
         /// <since_tizen> 3 </since_tizen>
         public MediaStreamBufferStatus Status { get; }

src/Tizen.Multimedia.MediaPlayer/Player/MediaStreamConfiguration.cs

@@ -59,10 +59,10 @@ internal MediaStreamConfiguration(MediaStreamSource owner, StreamType streamType
         public event EventHandler<MediaStreamSeekingOccurredEventArgs> SeekingOccurred;
 
         /// <summary>
-        /// Gets or sets the max size of the buffer.
+        /// Gets or sets the maximum size of the buffer for media stream.
         /// </summary>
-        /// <value>The max size of the buffer. The default is 200000.</value>
-        /// <remarks>If the buffer level overflows the max size, <see cref="BufferStatusChanged"/> will be raised with <see cref="MediaStreamBufferStatus.Overflow"/>.</remarks>
+        /// <value>The maximum size of the buffer in bytes. The default is 200000.</value>
+        /// <remarks>If the buffer level overflows the maximum size, <see cref="BufferStatusChanged"/> will be raised with <see cref="MediaStreamBufferStatus.Overflow"/>.</remarks>
         /// <exception cref="InvalidOperationException">The <see cref="MediaStreamSource"/> is not assigned to a player.</exception>
         /// <exception cref="ArgumentOutOfRangeException"><paramref name="value"/> is zero.</exception>
         /// <seealso cref="BufferStatusChanged"/>
@@ -95,7 +95,7 @@ public ulong BufferMaxSize
         }
 
         /// <summary>
-        /// Gets or sets the minimum threshold of the buffer.
+        /// Gets or sets the minimum threshold of the media stream buffer.
         /// </summary>
         /// <value>The minimum threshold of the buffer in percentage. The default is zero.</value>
         /// <remarks>If the buffer level drops below the threshold value, <see cref="BufferStatusChanged"/> will be raised with <see cref="MediaStreamBufferStatus.Underrun"/>.</remarks>

src/Tizen.Multimedia.MediaPlayer/Player/MediaStreamSeekingOccurredEventArgs.cs

@@ -35,8 +35,14 @@ public MediaStreamSeekingOccurredEventArgs(ulong offset)
         }
 
         /// <summary>
-        /// Gets the offset.
+        /// Gets the next new play position as a result of seeking operation.
         /// </summary>
+        /// <remarks>
+        /// The next playback position after SetPlayPositionAsync could be a little bit different with its input position.<br/>
+        /// So user should push the next media data using this time offset in nanoseconds.
+        /// </remarks>
+        /// <seealso cref="Player.SetPlayPositionAsync"/>
+        /// <seealso cref="Player.SetPlayPositionNanosecondsAsync"/>
         /// <since_tizen> 3 </since_tizen>
         public ulong Offset { get; }
 

src/Tizen.Multimedia.MediaPlayer/Player/MediaStreamSource.cs

@@ -37,7 +37,7 @@ public sealed class MediaStreamSource : MediaSource
         private static List<MediaFormatVideoMimeType> _supportedVideoFormats;
 
         /// <summary>
-        /// Gets all supported audio types.
+        /// Gets the supported audio types of the media stream source.
         /// </summary>
         /// <since_tizen> 3 </since_tizen>
         public static IEnumerable<MediaFormatAudioMimeType> SupportedAudioTypes
@@ -50,7 +50,7 @@ public static IEnumerable<MediaFormatAudioMimeType> SupportedAudioTypes
         }
 
         /// <summary>
-        /// Gets all supported video types.
+        /// Gets the supported video types of the media stream source.
         /// </summary>
         /// <since_tizen> 3 </since_tizen>
         public static IEnumerable<MediaFormatVideoMimeType> SupportedVideoTypes
@@ -214,7 +214,7 @@ public MediaStreamSource(VideoMediaFormat videoMediaFormat)
         public MediaStreamConfiguration VideoConfiguration { get; }
 
         /// <summary>
-        /// Pushes elementary stream to decode audio or video.
+        /// Pushes elementary stream to decode audio or video packet.
         /// </summary>
         /// <remarks>This source must be set as a source to a player and the player must be in the <see cref="PlayerState.Ready"/>,
         /// <see cref="PlayerState.Playing"/>, or <see cref="PlayerState.Paused"/> state.</remarks>

src/Tizen.Multimedia.MediaPlayer/Player/MediaUriSource.cs

@@ -20,7 +20,7 @@
 namespace Tizen.Multimedia
 {
     /// <summary>
-    /// Represents a media source with a uri.
+    /// Represents a media source with a URI.
     /// </summary>
     /// <remarks>
     /// The internet privilege(http://tizen.org/privilege/internet) must be added if any URLs are used to play from a network.
@@ -31,9 +31,10 @@ namespace Tizen.Multimedia
     /// <since_tizen> 3 </since_tizen>
     public sealed class MediaUriSource : MediaSource
     {
-        // TODO consider using Uri class.
+        // TODO consider using URI class.
         /// <summary>
-        /// Initializes a new instance of the MediaUriSource class with the specified uri.</summary>
+        /// Initializes a new instance of the MediaUriSource class with the specified URI.
+        /// </summary>
         /// <param name="uri">The uri string.</param>
         /// <remarks>For HTTP or RSTP, uri should start with "http://" or "rtsp://".
         /// The default protocol is "file://".
@@ -57,4 +58,3 @@ internal override void OnAttached(Player player)
         }
     }
 }
-

src/Tizen.Multimedia.MediaPlayer/Player/PlaybackInterruptedEventArgs.cs

@@ -35,7 +35,7 @@ public PlaybackInterruptedEventArgs(PlaybackInterruptionReason reason)
         }
 
         /// <summary>
-        /// Gets the reason.
+        /// Gets the reason for the playback interruption.
         /// </summary>
         /// <since_tizen> 3 </since_tizen>
         public PlaybackInterruptionReason Reason { get; }

src/Tizen.Multimedia.MediaPlayer/Player/Player.Properties.cs

@@ -193,7 +193,7 @@ public PlayerBufferingTime BufferingTime
         #endregion
 
         /// <summary>
-        /// Gets the state of the player.
+        /// Gets the current state of the player.
         /// </summary>
         /// <value>The current state of the player.</value>
         /// <exception cref="ObjectDisposedException">The player has already been disposed of.</exception>
@@ -258,7 +258,7 @@ public AudioLatencyMode AudioLatencyMode
         }
 
         /// <summary>
-        /// Gets or sets the looping state.
+        /// Gets or sets a value indicationg whether the media source is played in a loop.
         /// </summary>
         /// <value>true if the playback is looping; otherwise, false. The default value is false.</value>
         /// <exception cref="ObjectDisposedException">The player has already been disposed of.</exception>
@@ -286,7 +286,7 @@ public bool IsLooping
         private PlayerDisplaySettings _displaySettings;
 
         /// <summary>
-        /// Gets the display settings.
+        /// Gets the display settings of the player.
         /// </summary>
         /// <value>A <see cref="PlayerDisplaySettings"/> that specifies the display settings.</value>
         /// <since_tizen> 3 </since_tizen>
@@ -314,7 +314,7 @@ private void ReplaceDisplay(Display newDisplay)
         }
 
         /// <summary>
-        /// Gets or sets the display.
+        /// Gets or sets the display of the player.
         /// </summary>
         /// <value>A <see cref="Multimedia.Display"/> that specifies the display.</value>
         /// <remarks>
@@ -387,7 +387,7 @@ PlayerErrorCode IDisplayable<PlayerErrorCode>.ApplyEcoreWindow(IntPtr windowHand
         private PlayerTrackInfo _audioTrack;
 
         /// <summary>
-        /// Gets the track info for the audio.
+        /// Gets the audio track information of the player.
         /// </summary>
         /// <value>A <see cref="PlayerTrackInfo"/> for audio.</value>
         /// <since_tizen> 3 </since_tizen>
@@ -406,7 +406,7 @@ public PlayerTrackInfo AudioTrackInfo
         private PlayerTrackInfo _subtitleTrackInfo;
 
         /// <summary>
-        /// Gets the track info for the subtitle.
+        /// Gets the sutitle track information of the player.
         /// </summary>
         /// <value>A <see cref="PlayerTrackInfo"/> for the subtitle.</value>
         /// <since_tizen> 3 </since_tizen>
@@ -425,7 +425,7 @@ public PlayerTrackInfo SubtitleTrackInfo
         private StreamInfo _streamInfo;
 
         /// <summary>
-        /// Gets the stream information.
+        /// Gets the stream information of the player.
         /// </summary>
         /// <value>A <see cref="StreamInfo"/> for this player.</value>
         /// <since_tizen> 3 </since_tizen>
@@ -444,7 +444,7 @@ public StreamInfo StreamInfo
         private AudioEffect _audioEffect;
 
         /// <summary>
-        /// Gets the audio effect.
+        /// Gets the audio effect of the player.
         /// </summary>
         /// <feature>http://tizen.org/feature/multimedia.custom_audio_effect</feature>
         /// <exception cref="NotSupportedException">The required feature is not supported.</exception>
@@ -463,7 +463,7 @@ public AudioEffect AudioEffect
         }
 
         /// <summary>
-        /// Gets or sets the mute state.
+        /// Gets or sets a value indicationg whether the audio output of the player is muted.
         /// </summary>
         /// <value>true if the player is muted; otherwise, false.</value>
         /// <exception cref="ObjectDisposedException">The player has already been disposed of.</exception>
@@ -486,7 +486,7 @@ public bool Muted
         }
 
         /// <summary>
-        /// Gets or sets the current volume.
+        /// Gets or sets the current volume of the player.
         /// </summary>
         /// <remarks>Valid volume range is from 0 to 1.0, inclusive.</remarks>
         /// <exception cref="ObjectDisposedException">The player has already been disposed of.</exception>
@@ -520,7 +520,7 @@ public float Volume
         }
 
         /// <summary>
-        /// Gets or sets the audio-only state.
+        /// Gets or sets a value indicating whether the player is in audio only mode.
         /// </summary>
         /// <value>true if the playback is audio-only mode; otherwise, false. The default value is false.</value>
         /// The <see cref="Player"/> must be in the <see cref="PlayerState.Ready"/>,
@@ -547,7 +547,7 @@ public bool IsAudioOnly
         }
 
         /// <summary>
-        /// Gets or sets the player's replaygain state.
+        /// Gets or sets a value indicating whether the replay gain is enabled.
         /// </summary>
         /// <value>If the replaygain status is true, replaygain is applied (if contents has a replaygain tag);
         /// otherwise, the replaygain is not affected by tag and properties.</value>
@@ -585,8 +585,7 @@ public bool ReplayGain
         }
 
         /// <summary>
-        /// Enables or disables controlling the pitch of audio.
-        /// Gets the status of controlling the pitch of audio.
+        /// Gets or sets a value indicating whether the audio pitch control is enabled.
         /// </summary>
         /// <value>The value indicating whether or not AudioPitch is enabled. The default is false.</value>
         /// <remarks>This function is used for audio content only.
@@ -628,7 +627,7 @@ public bool AudioPitchEnabled
         }
 
         /// <summary>
-        /// Gets or sets the pitch of audio.
+        /// Gets or sets the pitch of the audio.
         /// </summary>
         /// <value>The audio stream pitch value. The default is 1.</value>
         /// <remarks>Enabling pitch control could increase the CPU usage on some devices.
@@ -783,7 +782,7 @@ public CodecType VideoCodecType
         private SphericalVideo _sphericalVideo;
 
         /// <summary>
-        /// Gets the spherical video settings.
+        /// Gets the spherical video porperties of the player.
         /// </summary>
         /// <since_tizen> 5 </since_tizen>
         public SphericalVideo SphericalVideo
@@ -802,7 +801,7 @@ public SphericalVideo SphericalVideo
         private AdaptiveVariants _adaptiveVariants;
 
         /// <summary>
-        /// Gets the adaptive variants settings.
+        /// Gets the adaptive variants of the player.
         /// </summary>
         /// <since_tizen> 5 </since_tizen>
         public AdaptiveVariants AdaptiveVariants
@@ -821,7 +820,7 @@ public AdaptiveVariants AdaptiveVariants
         private AudioOffload _audioOffload;
 
         /// <summary>
-        /// Gets the setting for audio offload.
+        /// Gets the audio offload settings of the player.
         /// </summary>
         /// <since_tizen> 6 </since_tizen>
         public AudioOffload AudioOffload