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 <sy.kwak@samsung.com>

diff --git a/include/sensor-internal.h b/include/sensor-internal.h
index 177f233fd5ee1a430e6c00431689a855da2fbb44..be8167fac8ea28150d112e4caf864ba56ff5219d 100644 (file)
--- 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);