[Tizen.System] Enhance API description

src/Tizen.System.Feedback/Feedback/Feedback.cs

@@ -413,6 +413,7 @@ public Feedback()
         /// bool res = feedback.IsSupportedPattern(FeedbackType.Vibration, "Tap");
         /// </code>
         /// </example>
+        /// <seealso cref="FeedbackType"/>
         public bool IsSupportedPattern(FeedbackType type, String pattern)
         {
             bool supported = false;
@@ -446,7 +447,7 @@ public bool IsSupportedPattern(FeedbackType type, String pattern)
         }
 
         /// <summary>
-        /// Plays a specific feedback pattern.
+        /// Plays specific type of reactions that are pre-defined feedback pattern.
         /// </summary>
         /// <remarks>
         /// To play Vibration type, app should have http://tizen.org/privilege/haptic privilege.
@@ -469,6 +470,8 @@ public bool IsSupportedPattern(FeedbackType type, String pattern)
         /// feedback.Play(FeedbackType.All, "Tap");
         /// </code>
         /// </example>
+        /// <seealso cref="FeedbackType"/>
+        /// <seealso cref="Feedback.Stop()"/>
         public void Play(FeedbackType type, String pattern)
         {
             int number;
@@ -503,7 +506,7 @@ public void Play(FeedbackType type, String pattern)
         }
 
         /// <summary>
-        /// Stops to play the feedback.
+        /// Stops various types of reactions from the feedback module.
         /// </summary>
         /// <remarks>
         /// To stop vibration, the application should have http://tizen.org/privilege/haptic privilege.
@@ -524,6 +527,7 @@ public void Play(FeedbackType type, String pattern)
         /// Feedback1.Stop();
         /// </code>
         /// </example>
+        /// <seealso cref="Feedback.Play(FeedbackType,String)"/>
         public void Stop()
         {
             Interop.Feedback.FeedbackError res = (Interop.Feedback.FeedbackError)Interop.Feedback.Stop();
@@ -549,7 +553,7 @@ public void Stop()
         }
 
         /// <summary>
-        /// Gets the count of theme can be used according to feedback type.
+        /// Gets the number of themes supported as described in the configuration.
         /// </summary>
         /// <remarks>
         /// Now this internal API works for FeedbackType.Sound only, FeedbackType.Vibration is not supported.
@@ -568,6 +572,7 @@ public void Stop()
         /// uint coundOfTheme = feedback.GetCountOfThemeInternal(FeedbackType.Sound);
         /// </code>
         /// </example>
+        /// <seealso cref="FeedbackType"/>
         [EditorBrowsable(EditorBrowsableState.Never)]
         public uint GetCountOfThemeInternal(FeedbackType type)
         {
@@ -596,7 +601,7 @@ public uint GetCountOfThemeInternal(FeedbackType type)
         }
 
         /// <summary>
-        /// Gets the id of theme selected.
+        /// Gets the current id of the theme selected from available themes described in the conf file.
         /// </summary>
         /// <remarks>
         /// Now this internal API works for FeedbackType.Sound only, FeedbackType.Vibration is not supported.
@@ -614,6 +619,7 @@ public uint GetCountOfThemeInternal(FeedbackType type)
         /// uint idOfTheme = feedback.GetThemeIdInternal(FeedbackType.Sound);
         /// </code>
         /// </example>
+        /// <seealso cref="FeedbackType"/>
         [EditorBrowsable(EditorBrowsableState.Never)]
         public uint GetThemeIdInternal(FeedbackType type)
         {
@@ -640,7 +646,7 @@ public uint GetThemeIdInternal(FeedbackType type)
         }
 
         /// <summary>
-        /// Sets the id of theme according to feedback type.
+        /// Sets the current id of the theme from available themes described in the conf file.
         /// </summary>
         /// <remarks>
         /// Now this internal API works for FeedbackType.Sound only, FeedbackType.Vibration is not supported.
@@ -661,6 +667,7 @@ public uint GetThemeIdInternal(FeedbackType type)
         /// feedback.SetThemeIdInternal(FeedbackType.Sound, idOfTheme);
         /// </code>
         /// </example>
+        /// <seealso cref="FeedbackType"/>
         [EditorBrowsable(EditorBrowsableState.Never)]
         public void SetThemeIdInternal(FeedbackType type, uint idOfTheme)
         {
@@ -687,7 +694,7 @@ public void SetThemeIdInternal(FeedbackType type, uint idOfTheme)
         }
 
         /// <summary>
-        /// Stops the current feedback playing by feedback type
+        /// Stops reactions of various types according to the feedback type.
         /// </summary>
         /// <remarks>
         /// To stop vibration, the application should have http://tizen.org/privilege/haptic privilege.
@@ -706,6 +713,7 @@ public void SetThemeIdInternal(FeedbackType type, uint idOfTheme)
         /// feedback.StopTypeInternal(FeedbackType.Vibration);
         /// </code>
         /// </example>
+        /// <seealso cref="FeedbackType"/>
         [EditorBrowsable(EditorBrowsableState.Never)]
         public void StopTypeInternal(FeedbackType type)
         {
@@ -734,11 +742,12 @@ public void StopTypeInternal(FeedbackType type)
         }
 
         /// <summary>
-        /// Gets the id array of theme supported.
+        /// Gets the array of theme ids supported described in the conf file.
         /// </summary>
         /// <remarks>
         /// Now this internal API works for FeedbackType.Sound only, FeedbackType.Vibration is not supported.
         /// The theme id is positive value as defined in the conf file.
+        /// Gets all theme ids as defined in the conf file.
         /// </remarks>
         /// <since_tizen> 10 </since_tizen>
         /// <param name="type">The feedback type.</param>
@@ -752,6 +761,7 @@ public void StopTypeInternal(FeedbackType type)
         /// uint[] getThemeIds = feedback.GetThemeIdsInternal(FeedbackType.Sound);
         /// </code>
         /// </example>
+        /// <seealso cref="FeedbackType"/>
         [EditorBrowsable(EditorBrowsableState.Never)]
         public uint[] GetThemeIdsInternal(FeedbackType type)
         {

src/Tizen.System/Device/Battery.cs

@@ -76,11 +76,20 @@ public static class Battery
     {
         private static readonly object s_lock = new object();
         /// <summary>
-        /// Gets the battery charge percentage.
+        /// Gets the current device's invalid battery charge percentage as an interger value.
         /// </summary>
+        /// <remarks>
+        /// It returns an integer value from 0 to 100 that indicates remaining battery charge as a percentage of the maximum level.
+        /// </remarks>
         /// <since_tizen> 3 </since_tizen>
         /// <value>It returns an integer value from 0 to 100 that indicates the remaining
         /// battery charge as a percentage of the maximum level.</value>
+        /// <example>
+        /// <code>
+        /// Console.WriteLine("battery Percent is: {0}", Tizen.System.Battery.Percent);
+        /// </code>
+        /// </example>
+        /// <seealso cref="BatteryPercentChangedEventArgs"/>
         public static int Percent
         {
             get
@@ -95,9 +104,25 @@ public static int Percent
             }
         }
         /// <summary>
-        /// Gets the current battery level.
+        /// Gets the current device's battery level status as a BatteryLevelStatus.
         /// </summary>
+        /// <remarks>
+        /// Retrieves the current battery level status based on remaining battery capacity.
+        /// </remarks>
         /// <since_tizen> 3 </since_tizen>
+        /// <value>The battery level status.</value>
+        /// <example>
+        /// <code>
+        /// using Tizen.System;
+        /// ...
+        /// BatteryLevelStatus status = Battery.Level;
+        /// if (Battery.Percent == 0 && status == BatteryLevelStatus.Empty)
+        ///     ...
+        /// ...
+        /// </code>
+        /// </example>
+        /// <seealso cref="BatteryLevelStatus"/>
+        /// <seealso cref="BatteryLevelChangedEventArgs"/>
         public static BatteryLevelStatus Level
         {
             get
@@ -112,9 +137,20 @@ public static BatteryLevelStatus Level
             }
         }
         /// <summary>
-        /// Gets the current charging state.
+        /// Gets the current device's charging state which the battery is charging.
         /// </summary>
+        /// <remarks>
+        /// Checks whether the battery is currently being charged or not.
+        /// </remarks>
         /// <since_tizen> 3 </since_tizen>
+        /// <example>
+        /// <code>
+        /// using Tizen.System;
+        /// bool charging = Battery.IsCharging;
+        /// ...
+        /// </code>
+        /// </example>
+        /// <seealso cref="BatteryChargingStateChangedEventArgs"/>
         public static bool IsCharging
         {
             get

src/Tizen.System/Device/Display.cs

@@ -75,9 +75,21 @@ private Display(int deviceNumber)
         }
 
         /// <summary>
-        /// The number of available display devices.
+        /// The number of available display devices connected to current device.
         /// </summary>
+        /// <remarks>
+        /// Retrieves the number of display devices connected to the system.
+        /// </remarks>
         /// <since_tizen> 3 </since_tizen>
+        /// <example>
+        /// <code>
+        /// using Tizen.System;
+        /// ...
+        /// Console.WriteLine("Total number of Displays are: {0}", Display.NumberOfDisplays);
+        /// </code>
+        /// </example>
+        /// <seealso cref="Display.MaxBrightness"/>
+        /// <seealso cref="Display.Brightness"/>
         public static int NumberOfDisplays
         {
             get
@@ -120,6 +132,9 @@ private static IReadOnlyList<Display> GetAllDisplayes()
         /// <summary>
         /// The maximum brightness value that can be set for the specific display.
         /// </summary>
+        /// <remarks>
+        /// Retrieves the maximum brightness level of a specific display device.
+        /// </remarks>
         /// <since_tizen> 3 </since_tizen>
         /// <example>
         /// <code>
@@ -142,20 +157,23 @@ public int MaxBrightness
         }
 
         /// <summary>
-        /// The brightness value of the display.
+        /// The brightness value of the specific display device.
         /// </summary>
         /// <remarks>
         /// The brightness value should be less than or equal to the MaxBrightness value.
         /// </remarks>
         /// <since_tizen> 3 </since_tizen>
         /// <exception cref="ArgumentException">When an invalid parameter value is set.</exception>
         /// <exception cref="UnauthorizedAccessException">If the privilege is not set.</exception>
+        /// <exception cref="InvalidOperationException">In case of any system error.</exception>
+        /// <exception cref="NotSupportedException">This exception can be due to device not supported.</exception>
         /// <example>
         /// <code>
         ///     Display display = Display.Displays[0];
         ///     Console.WriteLine("Display current Brightness is: {0}", display.Brightness);
         /// </code>
         /// </example>
+        /// <seealso cref="Display.MaxBrightness"/>
         public int Brightness
         {
             get
@@ -179,9 +197,27 @@ public int Brightness
             }
         }
         /// <summary>
-        /// The current device display state.
+        /// The current device display state, including normal, dim, and off states.
         /// </summary>
+        /// <remarks>
+        /// When the display state is set, it should be checked the profile version and supported display state.
+        /// </remarks>
         /// <since_tizen> 3 </since_tizen>
+        /// <example>
+        /// <code>
+        /// using Tizen.System;
+        /// ...
+        /// DisplayState current = Display.State;
+        /// Console.WriteLine("Display current state is: {0}", current);
+        /// ...
+        /// Display.State = DisplayState.Normal;
+        /// ...
+        /// </code>
+        /// </example>
+        /// <seealso cref="Power.RequestLock"/>
+        /// <seealso cref="Power.ReleaseLock"/>
+        /// <seealso cref="DisplayState"/>
+        /// <seealso cref="DisplayStateChangedEventArgs"/>
         public static DisplayState State
         {
             get
@@ -218,7 +254,7 @@ public static DisplayState State
         ///     {
         ///          Console.WriteLine("Display State is: {0}", args.State);
         ///     }
-        ///     Battery.StateChanged += handler;
+        ///     Display.StateChanged += handler;
         ///     await Task.Delay(20000);
         /// }
         /// </code>

src/Tizen.System/Device/Haptic.cs

@@ -73,9 +73,20 @@ private Vibrator(int id)
             Dispose(false);
         }
         /// <summary>
-        /// Gets the number of the available vibrators.
+        /// Gets the number of the available vibrators available on the current device.
         /// </summary>
+        /// <remarks>
+        /// Retrieves the total number of vibrators available on the device.
+        /// </remarks>
         /// <since_tizen> 3 </since_tizen>
+        /// <example>
+        /// <code>
+        /// using Tizen.System;
+        /// ...
+        /// Console.WriteLine("Total number of Vibrators are: {0}", Vibrator.NumberOfVibrators);
+        /// ...
+        /// </code>
+        /// </example>
         public static int NumberOfVibrators
         {
             get
@@ -121,6 +132,9 @@ private static IReadOnlyList<Vibrator> GetAllVibrators()
         /// Vibrates during the specified time with a constant intensity.
         /// This function can be used to start monotonous vibration for the specified time.
         /// </summary>
+        /// <remarks>
+        /// To prevent unexpected sleep (suspend) during vibration, please check and use Power module.
+        /// </remarks>
         /// <since_tizen> 3 </since_tizen>
         /// <param name="duration">The play duration in milliseconds.</param>
         /// <param name="feedback">The amount of the intensity variation (0 ~ 100).</param>
@@ -143,7 +157,8 @@ private static IReadOnlyList<Vibrator> GetAllVibrators()
         ///     }
         /// </code>
         /// </example>
-
+        /// <seealso cref="Vibrator.Stop()"/>
+        /// <seealso cref="Vibrator.Dispose()"/>
         public void Vibrate(int duration, int feedback)
         {
             IntPtr effect;
@@ -187,6 +202,7 @@ public void Vibrate(int duration, int feedback)
         ///     }
         /// </code>
         /// </example>
+        /// <seealso cref="Vibrator.Vibrate(int,int)"/>
         public void Stop()
         {
             if (_hapticHandle != IntPtr.Zero)
@@ -202,7 +218,22 @@ public void Stop()
         /// Dispose API for closing the internal resources.
         /// This function can be used to stop all the effects started by Vibrate().
         /// </summary>
+        /// <remarks>
+        /// Internally, it disconnects the connection to the vibrator by Vibrate().
+        /// </remarks>
         /// <since_tizen> 3 </since_tizen>
+        /// <example>
+        /// <code>
+        /// using Tizen.System;
+        /// ...
+        /// Vibrator vibrator = Vibrator.Vibrators[0];
+        /// vibrator.Vibrate(2000, 70);
+        /// ...
+        /// vibrator.Stop();
+        /// vibrator.Dispose(); 
+        /// </code>
+        /// </example>
+        /// <seealso cref="Vibrator.Vibrate(int,int)"/>
         public void Dispose()
         {
             Dispose(true);