From: Yunhee Seo <yuni.seo@samsung.com>
Date: Fri, 27 Sep 2024 10:57:54 +0000 (+0900)
Subject: ir: Enhance API description
X-Git-Tag: accepted/tizen/unified/20241006.053304~5
X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=a8678734c4aa5ec0997f0976840343781e72c28c;p=platform%2Fcore%2Fapi%2Fdevice.git

ir: Enhance API description

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

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

diff --git a/include/ir.h b/include/ir.h
index 957831a..e8429f0 100644
--- a/include/ir.h
+++ b/include/ir.h
@@ -35,37 +35,71 @@ extern "C" {
 
 
 /**
- * @brief Gets the information whether IR module is available.
+ * @brief Gets the information the IR module is available on the device.
+ * @details Gets the boolean value whether the IR module is available on the device. \n
+ *          If the IR module is available, the function returns @c true in the @a available parameter. \n
+ *          Otherwise, it returns @c false.
  * @since_tizen 3.0
+ * @remarks Ensure that the provided @a available pointer is valid and has enough memory allocated.
  * @privlevel public
  * @privilege %http://tizen.org/privilege/use_ir
  * @param[out] available The information whether IR is available
- * @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/ir.h>
+ * ...
+ * bool ir_available;
+ * int ret = device_ir_is_available(&ir_available);
+ * if (ret != DEVICE_ERROR_NONE) {
+ *     return -1;
+ * }
+ * ...
+ * if (ir_available) {
+ *     printf("IR module is available.\n");
+ * } else {
+ *     printf("IR module is not available.\n");
+ * }
+ * ...
+ * @endcode
  */
 int device_ir_is_available(bool *available);
 
 
 /**
- * @brief Transmits IR command.
+ * @brief Transmits IR command with the specified carrier frequency and pattern.
  * @since_tizen 3.0
  * @privlevel public
  * @privilege %http://tizen.org/privilege/use_ir
  * @param[in] carrier_frequency Carrier frequency to transmit IR command (Hertz)
  * @param[in] pattern Integer array of IR command
  * @param[in] size Size of IR command pattern
- * @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/ir.h>
+ * ...
+ * int carrier_frequency = 38000; // Carrier frequency in Hertz
+ * int pattern[] = {900, 450, 450, 450, 450, 450, 450, 450, 450, 450}; // Example IR command pattern
+ * int size = sizeof(pattern) / sizeof(pattern[0]); // Size of the IR command pattern
+ * int ret = device_ir_transmit(carrier_frequency, pattern, size);
+ * if (ret != DEVICE_ERROR_NONE) {
+ *     return -1;
+ * }
+ * printf("IR command transmitted successfully.\n");
+ * ...
+ * @endcode
+ * @see device_ir_is_available()
  */
 int device_ir_transmit(int carrier_frequency, int *pattern, int size);