From: SangYoun Kwak Date: Mon, 23 Sep 2024 08:25:12 +0000 (+0900) Subject: sensor-internal: Update description for sensor-internal APIs X-Git-Tag: accepted/tizen/unified/20240930.083349~2 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=eface3f81e0044e1b97cd768093b88c3ed858972;p=platform%2Fcore%2Fapi%2Fsensor.git sensor-internal: Update description for sensor-internal APIs The description of sensor-internal APIs are updated for the sections: @brief, @details, @remarks and @code. Change-Id: Ie5e801fd6a452f2e5572dbe56d4308319057ba2b Signed-off-by: SangYoun Kwak --- diff --git a/include/sensor-internal.h b/include/sensor-internal.h index 177f233..be8167f 100644 --- a/include/sensor-internal.h +++ b/include/sensor-internal.h @@ -28,16 +28,24 @@ extern "C" #endif /** - * @brief Enumeration for sensor types. + * @brief Enumeration for the sensor types for the internal sensor. + * @details This enumeration lists the different types of sensors. * @since_tizen 6.5 + * + * @remarks These values are used internally to identify and manage sensors. */ typedef enum { SENSOR_LIDAR = 1000, /**< Sensor type LIDAR */ } sensor_type_internel_e; /** - * @brief Enumeration for sensor handle attribute. + * @brief Enumeration for the sensor handle attribute value. + * @details This enumeration defines various attributes associated with sensor + * handles. * @since_tizen 7.0 + * + * @remarks Each attribute corresponds to specific properties of different + * sensors. */ typedef enum { @@ -49,7 +57,12 @@ typedef enum /** * @brief Enumeration for proximity sensitivity attribute value. + * @details This enumeration defines the different levels of sensitivity for the + * proximity sensor. * @since_tizen 7.0 + * + * @remarks With this enumeration, 3 levels are available: weak(1), medium(2) + * and strong(3). */ typedef enum { @@ -60,7 +73,11 @@ typedef enum /** * @brief Enumeration for lidar power state attribute value. + * @details This enumeration defines the possible power states for a LIDAR + * sensor. * @since_tizen 7.0 + * + * @remarks With this enumeration, 2 levels are available: off(0) and on(1). */ typedef enum { @@ -69,7 +86,8 @@ typedef enum } sensor_lidar_power_state_e; /** - * @brief Sets the attribute to a connected sensor. + * @brief Sets the specified sensor attribute to a connected sensor. + * @details Set the specified attributes of a connected sensor to the given value. * @since_tizen 6.5 * * @param[in] type a sensor type of represensting a connected sensor @@ -79,11 +97,15 @@ typedef enum * @retval 0 Successful * @retval -EINVAL Invalid parameter * @retval -EPERM Operation not permitted + * @code + * sensor_util_set_attribute_int(SENSOR_ACCELEROMETER, SENSOR_ATTRIBUTE_FLUSH, 1); + * @endcode */ int sensor_util_set_attribute_int(sensor_type_e type, sensor_attribute_e attr, int value); /** - * @brief Gets the attribute to a connected sensor. + * @brief Gets the specified sensor attribute from a connected sensor. + * @details Retrieve the specified sensor attribute value of a connected sensor. * @since_tizen 6.5 * * @param[in] type a sensor type of represensting a connected sensor @@ -93,16 +115,23 @@ int sensor_util_set_attribute_int(sensor_type_e type, sensor_attribute_e attr, i * @retval 0 Successful * @retval -EINVAL Invalid parameter * @retval -EPERM Operation not permitted + * @code + * int orientation; + * sensor_util_get_attribute_int(SENSOR_ACCELEROMETER, SENSOR_ATTRIBUTE_AXIS_ORIENTATION, orientation); + * @endcode */ int sensor_util_get_attribute_int(sensor_type_e type, sensor_attribute_e attr, int *value); /** * @brief Gets an attribute to control the behavior of a sensor listener. - * @details Applications can change the behavior of a sensor listener, for example, + * @details It is used to get the current setting of a specific attribute for a + * given sensor listener. + * @since_tizen 7.0 + * + * @remarks Applications can change the behavior of a sensor listener, for example, * what is the reference coordinate of the sensor values, * and when the system is allowed to turn off the sensor implicitly to reduce the power consumption. * See #sensor_attribute_e for more details about the available control parameters. - * @since_tizen 7.0 * * @param[in] listener A listener handle * @param[in] attribute An attribute to change. @@ -114,11 +143,18 @@ int sensor_util_get_attribute_int(sensor_type_e type, sensor_attribute_e attr, i * @retval #SENSOR_ERROR_NONE Successful * @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter * @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed + * @code + * int sensitivity; + * sensor_listener_get_attribute_int(listener, SENSOR_ATTRIBUTE_AXIS_ORIENTATION, &sensitivity); + * @endcode */ int sensor_listener_get_attribute_int(sensor_listener_h listener, sensor_attribute_e attribute, int *value); /** - * @brief Sets the attribute to a connected sensor. + * @brief Sets the sensor handle attribute to a connected sensor. + * @details Set the specified attribute of a connected sensor to the given value. + * Note that each attribute has a specific range of values or uses + * fixed enumerations. * @since_tizen 7.0 * * @remarks Each attribute has a range of values or use fixed enum. @@ -133,13 +169,21 @@ int sensor_listener_get_attribute_int(sensor_listener_h listener, sensor_attribu * @retval #SENSOR_ERROR_NONE Successful * @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter * @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed + * @code + * sensor_set_attribute_int(sensor, SENSOR_HANDLE_ATTR_PROXIMITY_SENSITIVITY_LEVEL, 1); + * @endcode */ int sensor_set_attribute_int(sensor_h sensor, sensor_handle_attribute_e attribute, int value); /** - * @brief Gets the attribute to a connected sensor. + * @brief Gets the sensor handle attribute from a connected sensor. + * @details Retrieve the specified sensor handle attribute value of a connected sensor. * @since_tizen 7.0 * + * @remarks Each attribute has a range of values or use fixed enum. + * For example, the type of return value of proximity sensitivity level + * attribute can be only sensor_proximity_sensitivity_level_e. + * * @param[in] sensor a sensor handle of represensting a connected sensor * @param[in] attr an attribute to change * @param[out] value an attribute value @@ -148,6 +192,10 @@ int sensor_set_attribute_int(sensor_h sensor, sensor_handle_attribute_e attribut * @retval #SENSOR_ERROR_NONE Successful * @retval #SENSOR_ERROR_INVALID_PARAMETER Invalid parameter * @retval #SENSOR_ERROR_OPERATION_FAILED Operation failed + * @code + * int sensitivity_level; + * sensor_get_attribute_int(sensor, SENSOR_HANDLE_ATTR_PROXIMITY_SENSITIVITY_LEVEL, &sensitivity_level); + * @endcode */ int sensor_get_attribute_int(sensor_h sensor, sensor_handle_attribute_e attribute, int *value);