From: Yunhee Seo Date: Fri, 27 Sep 2024 08:04:03 +0000 (+0900) Subject: haptic: Enhance API description X-Git-Tag: accepted/tizen/unified/20241006.053304~7 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=d23f9bd4999026ab919b8bc33a816c88df246f64;p=platform%2Fcore%2Fapi%2Fdevice.git haptic: Enhance API description To improve readability and facilitate comprehension, more detailed API descriptions are added. Change-Id: I255f140a71adecc0cf13ba4bcd59e9a5bc2598c7 Signed-off-by: Yunhee Seo --- diff --git a/include/haptic.h b/include/haptic.h index e1985a6..55a9019 100644 --- 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 + * ... + * 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 + * ... + * 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 + * ... + * 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 + * ... + * 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);