led: Enhance API description

To improve readability and facilitate comprehension,
more detailed API descriptions are added.

Change-Id: Ic33e085bf810418208eec37d40bc59d6c58eadf0
Signed-off-by: Yunhee Seo <yuni.seo@samsung.com>

diff --git a/include/led-internal.h b/include/led-internal.h
index 0550b35a7cae4a587de4a0959a7fd1ed45072d4d..2fa60e78981665fb62c77d3c9d997111cbd7e9a1 100644 (file)
--- a/include/led-internal.h
+++ b/include/led-internal.h
@@ -28,24 +28,40 @@ extern "C" {
 
 
 /**
- * @brief Gets the total number of LEDs in the device.
+ * @brief Gets the the total number of LEDs present on the current device.
+ * @details Retrieves the total number of LEDs present on the device. \n
+ *          The number of LEDs is returned in the @a num_of_leds parameter.
  * @since_tizen 5.0
  * @privlevel public
  * @privilege %http://tizen.org/privilege/led
  * @remarks This API is related to the following feature: %http://tizen.org/feature/led
- * @param[out] Number of LEDs
- * @return @c 0 on success,
- *         otherwise a negative error value
+ * @param[out] num_of_leds A pointer to an integer where the number of LEDs will be stored.
+ * @return @c 0 on success, otherwise a negative error value
  * @retval #DEVICE_ERROR_NONE Successful
  * @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
  * @retval #DEVICE_ERROR_PERMISSION_DENIED Permission denied
  * @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
  * @retval #DEVICE_ERROR_NOT_SUPPORTED Not supported device
+ * @code
+ * ...
+ * #include <stdio.h>
+ * #include <device/led-internal.h>
+ * ...
+ * int num_of_leds;
+ * int ret = device_multi_led_get_number(&num_of_leds);
+ * if (ret == DEVICE_ERROR_NONE) {
+ *     ...
+ * }
+ * ...
+ * @endcode
  */
 int device_multi_led_get_number(int *num_of_leds);
 
 /**
- * @brief Plays multiple LEDs at the same time.
+ * @brief Plays the current device's multiple LEDs at the same time.
+ * @details This function controls the colors of multiple LEDs on the device simultaneously. \n
+ *          The colors are specified in the color array parameter, where each element represents the color of one LED.
+ *          The first byte of each element represents the opacity of the color, and the remaining three bytes represent the red, green, and blue components of the color.
  * @since_tizen 5.0
  * @privlevel public
  * @privilege %http://tizen.org/privilege/led
@@ -53,13 +69,33 @@ int device_multi_led_get_number(int *num_of_leds);
  * @remarks The array size must be the same as the number of LEDs, which is obtained by device_multi_led_get_number().
  * @param[in] color[] The Color value for each LED\n
  *                    The first byte means opaque, and the other 3 bytes mean RGB values
- * @return @c 0 on success,
- *         otherwise a negative error value
+ * @return @c 0 on success, otherwise a negative error value
  * @retval #DEVICE_ERROR_NONE Successful
  * @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
  * @retval #DEVICE_ERROR_PERMISSION_DENIED Permission denied
  * @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
  * @retval #DEVICE_ERROR_NOT_SUPPORTED Not supported device
+ * @code
+ * #include <stdio.h>
+ * #include <device/led-internal.h>
+ * ...
+ * int num_of_leds;
+ * int ret = device_multi_led_get_number(&num_of_leds);
+ * if (ret != DEVICE_ERROR_NONE) {
+ *     return -1;
+ * }
+ * ...
+ * unsigned int colors[num_of_leds];
+ * for (int i = 0; i < num_of_leds; i++) {
+ *     colors[i] = 0xFF0000; // Red color with full opacity
+ * }
+ * ret = device_multi_led_control(colors);
+ * if (ret == DEVICE_ERROR_NONE) {
+ *     ...
+ * }
+ * ...
+ * @endcode
+ * @see device_multi_led_get_number()
  */
 int device_multi_led_control(unsigned int color[]);
 

diff --git a/include/led.h b/include/led.h
index 511c5ae0eeaef2976311edf453daa2a921c615b2..62bbc3245ed6ea799e71c7c38c5b3c680e52bce6 100644 (file)
--- a/include/led.h
+++ b/include/led.h
@@ -35,56 +35,88 @@ extern "C" {
 
 /**
  * @brief Gets the max brightness value of a LED that is located next to the camera.
+ * @details Retrieves the maximum brightness level of the back camera flash.
  * @since_tizen 2.3
  * @privlevel public
  * @privilege %http://tizen.org/privilege/led
  * @remarks This API is related to the following feature: %http://tizen.org/feature/camera.back.flash
  * @param[out] max_brightness The max brightness value of the LED
- * @return @c 0 on success,
- *         otherwise a negative error value
+ * @return @c 0 on success, otherwise a negative error value
  * @retval #DEVICE_ERROR_NONE Successful
  * @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
  * @retval #DEVICE_ERROR_PERMISSION_DENIED Permission denied
  * @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
  * @retval #DEVICE_ERROR_NOT_SUPPORTED Not supported device
+ * @code
+ * #include <device/led.h>
+ * ...
+ * int max_brightness = 0;
+ * int ret = 0;
+ * ...
+ * ret = device_flash_get_max_brightness(&max_brightness);
+ * ...
+ * @endcode
  */
 int device_flash_get_max_brightness(int *max_brightness);
 
 
 /**
  * @brief Gets the brightness value of a LED that is located next to the camera.
+ * @details Retrieves the current brightness level of the back camera flash. \n
+ *          The brightness level is filled in the @a brightness parameter.
  * @since_tizen 2.3
  * @privlevel public
  * @privilege %http://tizen.org/privilege/led
  * @remarks This API is related to the following feature: %http://tizen.org/feature/camera.back.flash
  * @param[out] brightness The brightness value of LED (@c 0 ~ MAX)
- * @return @c 0 on success,
- *         otherwise a negative error value
+ * @return @c 0 on success, otherwise a negative error value
  * @retval #DEVICE_ERROR_NONE Successful
  * @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
  * @retval #DEVICE_ERROR_PERMISSION_DENIED Permission denied
  * @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
  * @retval #DEVICE_ERROR_NOT_SUPPORTED Not supported device
+ * @code
+ * #include <device/led.h>
+ * ...
+ * int brightness = 0;
+ * int ret = 0;
+ * ...
+ * ret = device_flash_get_brightness(&brightness);
+ * ...
+ * @endcode
+ * @see device_flash_set_brightness()
  */
 int device_flash_get_brightness(int *brightness);
 
 
 /**
  * @brief Sets the brightness value of a LED that is located next to the camera.
+ * @details Sets the brightness level of the back camera flash. \n
+ *          The desired brightness level is specified in the @a brightness parameter.
  * @since_tizen 2.3
  * @privlevel public
  * @privilege %http://tizen.org/privilege/led
  * @remarks Since 2.4, this API check camera flash status whether camera API preempted flash or not, so it could be failed if flash was preempted by camera API. In this case, API will return #DEVICE_ERROR_RESOURCE_BUSY error.
  *          This API is related to the following feature: %http://tizen.org/feature/camera.back.flash
  * @param[in] brightness The brightness value of LED (@c 0 ~ MAX)
- * @return @c 0 on success,
- *         otherwise a negative error value
+ * @return @c 0 on success, otherwise a negative error value
  * @retval #DEVICE_ERROR_NONE Successful
  * @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
  * @retval #DEVICE_ERROR_PERMISSION_DENIED Permission denied
  * @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
  * @retval #DEVICE_ERROR_NOT_SUPPORTED Not supported device
  * @retval #DEVICE_ERROR_RESOURCE_BUSY Device or resource busy
+ * @code
+ * #include <device/led.h>
+ * ...
+ * int brightness = 0;
+ * int ret = 0;
+ * ...
+ * ret = device_flash_set_brightness(brightness);
+ * ...
+ * @endcode
+ * @see device_flash_get_max_brightness()
+ * @see device_flash_get_brightness()
  */
 int device_flash_set_brightness(int brightness);
 
@@ -110,30 +142,60 @@ typedef enum {
  * @param[in] color The Color value \n
  *                  The first byte means opaque and the other 3 bytes are RGB values
  * @param[in] flags The combination of enum #led_custom_flags
- * @return @c 0 on success,
- *         otherwise a negative error value
+ * @return @c 0 on success, otherwise a negative error value
  * @retval #DEVICE_ERROR_NONE Successful
  * @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
  * @retval #DEVICE_ERROR_PERMISSION_DENIED Permission denied
  * @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
  * @retval #DEVICE_ERROR_NOT_SUPPORTED Not supported device
+ * @code
+ * #include <stdio.h>
+ * #include <device/led.h>
+ * ...
+ * int on_time = 100; // On time in milliseconds
+ * int off_time = 200; // Off time in milliseconds
+ * unsigned int color = 0xFF0000; // Red color with full opacity
+ * unsigned int flags = LED_CUSTOM_DEFAULT; // Default flag
+ * int ret = device_led_play_custom(on_time, off_time, color, flags);
+ * if (ret != DEVICE_ERROR_NONE) {
+ *     ...
+ *     return -1;
+ * }
+ * printf("Custom effect played successfully.\n");
+ * ...
+ * @endcode
+ * @see device_led_stop_custom()
  */
 int device_led_play_custom(int on, int off, unsigned int color, unsigned int flags);
 
 
 /**
  * @brief Stops the custom effect of the service LED that is located to the front of a device.
+ * @details Stops the custom effect of the service LED located at the front of the device.
+ *          The custom effect was started by calling device_led_play_custom().
  * @since_tizen 2.3
  * @privlevel public
  * @privilege %http://tizen.org/privilege/led
- * @remarks This API is related to the following feature: %http://tizen.org/feature/led
- * @return @c 0 on success,
- *         otherwise a negative error value
+ * @remarks This API is related to the following feature: %http://tizen.org/feature/led \n
+ *          Requested custom effects by device_led_play_custom() are removed.
+ * @return @c 0 on success, otherwise a negative error value
  * @retval #DEVICE_ERROR_NONE Successful
  * @retval #DEVICE_ERROR_INVALID_PARAMETER Invalid parameter
  * @retval #DEVICE_ERROR_PERMISSION_DENIED Permission denied
  * @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
  * @retval #DEVICE_ERROR_NOT_SUPPORTED Not supported device
+ * @code
+ * #include <device/led.h>
+ * ...
+ * int ret = device_led_play_custom(100, 200, 0xFF0000, LED_CUSTOM_DEFAULT);
+ * if (ret != DEVICE_ERROR_NONE) {
+ *     return -1;
+ * }
+ * sleep(5); // Wait for 5 seconds
+ * ret = device_led_stop_custom();
+ * ...
+ * @endcode
+ * @see device_led_play_custom()
  */
 int device_led_stop_custom(void);