haptic: Enhance API description

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

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

diff --git a/include/haptic.h b/include/haptic.h
index e1985a62449317c8fb69afb7309d10dcfe9950c2..55a90198edc68611b0ae3e089c0e216ca7d3cf83 100644 (file)
--- a/include/haptic.h
+++ b/include/haptic.h
@@ -48,25 +48,35 @@ typedef void* haptic_effect_h;
 
 
 /**
- * @brief Gets the number of vibrators.
+ * @brief Gets the number of vibrators available on the current device.
+ * @details Retrieves the total number of vibrators available on the device.
+ *          The number of vibrators is returned in the @a device_number parameter.
  * @since_tizen 2.3
  * @privlevel public
  * @privilege %http://tizen.org/privilege/haptic
+ * @remarks Ensure that the provided @a device_number pointer is valid and has enough memory allocated.
  * @param[in] device_number The number of vibrators
- * @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/haptic.h>
+ * ...
+ * int num_of_haptic_device = 0;
+ * int ret = 0;
+ * ...
+ * ret = device_haptic_get_count(&num_of_haptic_device);
+ * @endcode
  */
 int device_haptic_get_count(int *device_number);
 
 
 /**
- * @brief Opens a haptic-vibration device.
- * @details Internally, it makes a connection to the vibrator.
+ * @brief Opens a haptic-vibration device with the given @a device_index.
+ * @details Internally, it makes a connection to control the vibrator.
  * @since_tizen 2.3
  * @privlevel public
  * @privilege %http://tizen.org/privilege/haptic
@@ -75,8 +85,7 @@ int device_haptic_get_count(int *device_number);
  * @param[in] device_index The index of device what you want to vibrate \n
  *                         The index starts from @c 0
  * @param[out] device_handle The handle of vibrator
- * @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
@@ -89,27 +98,39 @@ int device_haptic_get_count(int *device_number);
  * int ret = device_haptic_open(0, &haptic_device);
  * ...
  * ret = device_haptic_close(haptic_device);
+ * ...
  * @endcode
  * @see device_haptic_close()
+ * @see haptic_device_h
  */
 int device_haptic_open(int device_index, haptic_device_h *device_handle);
 
 
 /**
- * @brief Closes a haptic-vibration device.
- * @details Internally, it disconnects the connection to the vibrator.
+ * @brief Closes a haptic-vibration device by haptic device handler.
+ * @details Internally, it disconnects the connection to the vibrator by haptic device handler.
  * @since_tizen 2.3
  * @privlevel public
  * @privilege %http://tizen.org/privilege/haptic
+ * @remarks Ensure The @a device_handle should be get properly by device_haptic_open().
  * @param[in] device_handle The device handle from device_haptic_open()
- * @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/haptic.h>
+ * ...
+ * haptic_device_h haptic_device;
+ * int ret = device_haptic_open(0, &haptic_device);
+ * ...
+ * ret = device_haptic_close(haptic_device);
+ * ...
+ * @endcode
  * @see device_haptic_open()
+ * @see haptic_device_h
  */
 int device_haptic_close(haptic_device_h device_handle);
 
@@ -127,34 +148,62 @@ int device_haptic_close(haptic_device_h device_handle);
  * @param[in] duration The play duration in milliseconds
  * @param[in] feedback The amount of the intensity variation (@c 0 ~ @c 100)
  * @param[out] effect_handle The pointer to the variable that will receive a handle to the playing effect
- * @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/haptic.h>
+ * ...
+ * haptic_device_h haptic_device;
+ * haptic_effect_h haptic_effect;
+ * int ret = device_haptic_open(0, &haptic_device);
+ * ...
+ * ret = device_haptic_vibrate(haptic_device, 500, 50, &haptic_effect);
+ * ...
+ * ret = device_haptic_close(haptic_device);
+ * ...
+ * @endcode
  * @see device_haptic_stop()
+ * @see haptic_device_h
+ * @see haptic_effect_h
  */
 int device_haptic_vibrate(haptic_device_h device_handle, int duration, int feedback, haptic_effect_h *effect_handle);
 
 
 /**
- * @brief Stops all vibration effects which are being played.
+ * @brief Stops all vibration effects which are being played by haptic device handler.
  * @details This function can be used to stop all effects started by device_haptic_vibrate().
  * @since_tizen 2.3
  * @privlevel public
  * @privilege %http://tizen.org/privilege/haptic
  * @param[in] device_handle The device handle from device_haptic_open()
  * @param[in] effect_handle The effect handle from device_haptic_vibrate()
- * @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/haptic.h>
+ * ...
+ * haptic_device_h haptic_device;
+ * haptic_effect_h haptic_effect;
+ * int ret = device_haptic_open(0, &haptic_device);
+ * ...
+ * ret = device_haptic_vibrate(haptic_device, 500, 50, &haptic_effect);
+ * ...
+ * ret = device_haptic_stop(haptic_device, haptic_effect);
+ * ...
+ * ret = device_haptic_close(haptic_device);
+ * ...
+ * @endcode
  * @see device_haptic_vibrate()
+ * @see haptic_device_h
+ * @see haptic_effect_h
  */
 int device_haptic_stop(haptic_device_h device_handle, haptic_effect_h effect_handle);