callback: Enhance API description

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

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

diff --git a/include/callback.h b/include/callback.h
index afc8feea009f8090276b3dd0d698ad69097c5192..29b1bc00ffa8620b12b979f8ce970f6525877db6 100644 (file)
--- a/include/callback.h
+++ b/include/callback.h
@@ -49,7 +49,7 @@ typedef enum {
 
 
 /**
- * @brief Called when a device status is changed.
+ * @brief Called when a device status is changed (e.g., battery_capacity, display_state, etc).
  * @details Each device callback has a different output param type. \n
  *          So you need to check below output param before using this function. \n
  *                  callback enum               output type \n
@@ -63,40 +63,84 @@ typedef enum {
  * @param[out] type The device type to monitor
  * @param[out] value The changed value
  * @param[out] user_data The user data passed from the callback registration function
+ * @see device_add_callback
+ * @see device_remove_callback
  */
 typedef void (*device_changed_cb)(device_callback_e type, void *value, void *user_data);
 
 
 /**
- * @brief Adds a callback to the observing device state.
+ * @brief Adds a callback to the observing device state (e.g., battery, display, etc).
+ * @details Registers a callback function to be invoked when a specified device status changes. \n
+ *          When the device status changes, the registered callback function will be called with the new status value as an argument.
  * @since_tizen 2.3
  * @remarks The following feature should be supported for #DEVICE_CALLBACK_DISPLAY_STATE: %http://tizen.org/feature/display. Otherwise #DEVICE_ERROR_NOT_SUPPORTED is returned.
  * @param[in] type The device type to monitor
  * @param[in] callback The callback function to add
  * @param[in] user_data The user data to be passed to the callback function
- * @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_ALREADY_IN_PROGRESS Operation already
  * @retval #DEVICE_ERROR_OPERATION_FAILED Operation failed
  * @retval #DEVICE_ERROR_NOT_SUPPORTED Not supported device
+ * @code
+ * #include <device/callback.h>
+ * ...
+ * static void device_display_state_changed_cb(device_callback_e type, void *value, void *user_data)
+ * {
+ *      int display_state = (int)((intptr_t) value);
+ *      ...
+ * }
+ * ...
+ * int main(void)
+ * {
+ *     int ret = 0;
+ *     device_add_callback(DEVICE_CALLBACK_DISPLAY_STATE, device_display_state_changed_cb, NULL);
+ *     ...
+ * }
+ * ...
+ * @endcode
+ * @see device_callback_e
+ * @see device_changed_cb
+ * @see device_remove_callback
  */
 int device_add_callback(device_callback_e type, device_changed_cb callback, void *user_data);
 
 
 /**
- * @brief Removes a device callback function.
+ * @brief Removes a device callback function that was added with device_add_callback().
+ * @details After calling this, the specified callback function will no longer be called when the device status changes.
  * @since_tizen 2.3
  * @remarks The following feature should be supported for #DEVICE_CALLBACK_DISPLAY_STATE: %http://tizen.org/feature/display. Otherwise #DEVICE_ERROR_NOT_SUPPORTED is returned.
  * @param[in] type The device type to monitor
  * @param[in] callback The callback function to remove
- * @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_OPERATION_FAILED Operation failed
  * @retval #DEVICE_ERROR_NOT_SUPPORTED Not supported device
+ * @code
+ * #include <device/callback.h>
+ * ...
+ * static void device_display_state_changed_cb(device_callback_e type, void *value, void *user_data)
+ * {
+ *      int display_state = (int)((intptr_t) value);
+ *      ...
+ * }
+ * ...
+ * int main(void)
+ * {
+ *     int ret = 0;
+ *     device_add_callback(DEVICE_CALLBACK_DISPLAY_STATE, device_display_state_changed_cb, NULL);
+ *     ...
+ *     device_remove_callback(DEVICE_CALLBACK_DISPLAY_STATE, device_display_state_changed_cb);
+ * }
+ * ...
+ * @endcode
+ * @see device_callback_e
+ * @see device_changed_cb
+ * @see device_add_callback
  */
 int device_remove_callback(device_callback_e type, device_changed_cb callback);