sensing: fix doxygen warnings

Add missing doxygen comments in various sensing headers.

Signed-off-by: Zhang Lixu <[email protected]>

Author: lixuzha

include/zephyr/sensing/sensing.h

@@ -38,16 +38,20 @@ extern "C" {
  */
 struct sensing_sensor_version {
 	union {
-		uint32_t value;
+		uint32_t value; /**< The version represented as a 32-bit value. */
 		struct {
-			uint8_t major;
-			uint8_t minor;
-			uint8_t hotfix;
-			uint8_t build;
+			uint8_t major;  /**< The major version number. */
+			uint8_t minor;  /**< The minor version number. */
+			uint8_t hotfix; /**< The hotfix version number. */
+			uint8_t build;  /**< The build version number. */
 		};
 	};
 };
 
+/**
+ * @brief Macro to create a sensor version value.
+ *
+ */
 #define SENSING_SENSOR_VERSION(_major, _minor, _hotfix, _build)         \
 				(FIELD_PREP(GENMASK(31, 24), _major) |  \
 				 FIELD_PREP(GENMASK(23, 16), _minor) |  \
@@ -83,36 +87,36 @@ struct sensing_sensor_version {
  *
  */
 enum sensing_sensor_state {
-	SENSING_SENSOR_STATE_READY = 0,
-	SENSING_SENSOR_STATE_OFFLINE = 1,
+	SENSING_SENSOR_STATE_READY = 0,   /**< The sensor is ready. */
+	SENSING_SENSOR_STATE_OFFLINE = 1, /**< The sensor is offline. */
 };
 
 /**
  * @brief Sensing subsystem sensor config attribute
  *
  */
 enum sensing_sensor_attribute {
+	/** The interval attribute of a sensor configuration. */
 	SENSING_SENSOR_ATTRIBUTE_INTERVAL = 0,
+	/** The sensitivity attribute of a sensor configuration. */
 	SENSING_SENSOR_ATTRIBUTE_SENSITIVITY = 1,
+	/** The latency attribute of a sensor configuration. */
 	SENSING_SENSOR_ATTRIBUTE_LATENCY = 2,
+	/** The maximum number of attributes that a sensor configuration can have. */
 	SENSING_SENSOR_ATTRIBUTE_MAX,
 };
 
-
 /**
  * @brief Define Sensing subsystem sensor handle
  *
  */
 typedef void *sensing_sensor_handle_t;
 
-
 /**
  * @brief Sensor data event receive callback.
  *
  * @param handle The sensor instance handle.
- *
  * @param buf The data buffer with sensor data.
- *
  * @param context User provided context pointer.
  */
 typedef void (*sensing_data_event_t)(
@@ -151,41 +155,52 @@ struct sensing_sensor_info {
  *
  */
 struct sensing_callback_list {
-	sensing_data_event_t on_data_event;
-	void *context;
+	sensing_data_event_t on_data_event; /**< Callback function for a sensor data event. */
+	void *context;                      /**< Associated context with on_data_event */
 };
+
 /**
  * @struct sensing_sensor_config
  * @brief Sensing subsystem sensor configure, including interval, sensitivity, latency
  *
  */
 struct sensing_sensor_config {
-	enum sensing_sensor_attribute attri;
+	enum sensing_sensor_attribute attri; /**< Attribute of the sensor configuration. */
 
 	/** \ref SENSING_SENSITIVITY_INDEX_ALL */
-	int8_t data_field;
+	int8_t data_field; /**< Data field of the sensor configuration. */
 
 	union {
+		/** Interval between two sensor samples in microseconds (us). */
 		uint32_t interval;
+
+		/**
+		 * Sensitivity threshold for reporting new data. A new sensor sample is reported
+		 * only if the difference between it and the previous sample exceeds this
+		 * sensitivity value.
+		 */
 		uint32_t sensitivity;
+
+		/**
+		 * Maximum duration for batching sensor samples before reporting in
+		 * microseconds (us). This defines how long sensor samples can be
+		 * accumulated before they must be reported.
+		 */
 		uint64_t latency;
 	};
 };
 
-
- /**
-  * @brief Get all supported sensor instances' information.
-  *
-  * This API just returns read only information of sensor instances, pointer info will
-  * directly point to internal buffer, no need for caller to allocate buffer,
-  * no side effect to sensor instances.
-  *
-  * @param num_sensors Get number of sensor instances.
-  *
-  * @param info For receiving sensor instances' information array pointer.
-  *
-  * @return 0 on success or negative error value on failure.
-  */
+/**
+ * @brief Get all supported sensor instances' information.
+ *
+ * This API just returns read only information of sensor instances, pointer info will
+ * directly point to internal buffer, no need for caller to allocate buffer,
+ * no side effect to sensor instances.
+ *
+ * @param num_sensors Get number of sensor instances.
+ * @param info For receiving sensor instances' information array pointer.
+ * @return 0 on success or negative error value on failure.
+ */
 int sensing_get_sensors(int *num_sensors, const struct sensing_sensor_info **info);
 
 /**
@@ -197,12 +212,9 @@ int sensing_get_sensors(int *num_sensors, const struct sensing_sensor_info **inf
  * meanwhile, also register sensing callback list
  *
  * @param info The sensor info got from \ref sensing_get_sensors
- *
  * @param cb_list callback list to be registered to sensing, must have a static
  *                lifetime.
- *
  * @param handle The opened instance handle, if failed will be set to NULL.
- *
  * @return 0 on success or negative error value on failure.
  */
 int sensing_open_sensor(
@@ -219,12 +231,9 @@ int sensing_open_sensor(
  * meanwhile, also register sensing callback list.
  *
  * @param dev pointer device get from device tree.
- *
  * @param cb_list callback list to be registered to sensing, must have a static
  *                lifetime.
- *
  * @param handle The opened instance handle, if failed will be set to NULL.
- *
  * @return 0 on success or negative error value on failure.
  */
 int sensing_open_sensor_by_dt(
@@ -235,7 +244,6 @@ int sensing_open_sensor_by_dt(
  * @brief Close sensor instance.
  *
  * @param handle The sensor instance handle need to close.
- *
  * @return 0 on success or negative error value on failure.
  */
 int sensing_close_sensor(
@@ -245,11 +253,8 @@ int sensing_close_sensor(
  * @brief Set current config items to Sensing subsystem.
  *
  * @param handle The sensor instance handle.
- *
  * @param configs The configs to be set according to config attribute.
- *
  * @param count count of configs.
- *
  * @return 0 on success or negative error value on failure, not support etc.
  */
 int sensing_set_config(
@@ -260,11 +265,8 @@ int sensing_set_config(
  * @brief Get current config items from Sensing subsystem.
  *
  * @param handle The sensor instance handle.
- *
  * @param configs The configs to be get according to config attribute.
- *
  * @param count count of configs.
- *
  * @return 0 on success or negative error value on failure, not support etc.
  */
 int sensing_get_config(
@@ -275,7 +277,6 @@ int sensing_get_config(
  * @brief Get sensor information from sensor instance handle.
  *
  * @param handle The sensor instance handle.
- *
  * @return a const pointer to \ref sensing_sensor_info on success or NULL on failure.
  */
 const struct sensing_sensor_info *sensing_get_sensor_info(
@@ -289,5 +290,4 @@ const struct sensing_sensor_info *sensing_get_sensor_info(
  * @}
  */
 
-
 #endif /*ZEPHYR_INCLUDE_SENSING_H_*/

include/zephyr/sensing/sensing_datatypes.h

@@ -45,9 +45,9 @@
  * system/chre/chre_api/include/chre_api/chre/sensor_types.h
  */
 struct sensing_sensor_value_header {
-	/** base timestamp of this data readings, unit is micro seconds */
+	/** Base timestamp of this data readings, unit is micro seconds */
 	uint64_t base_timestamp;
-	/** count of this data readings */
+	/** Count of this data readings */
 	uint16_t reading_count;
 };
 
@@ -65,19 +65,28 @@ struct sensing_sensor_value_header {
  * q31 version
  */
 struct sensing_sensor_value_3d_q31 {
+	/** Header of the sensor value data structure. */
 	struct sensing_sensor_value_header header;
-	int8_t shift;
+	int8_t shift; /**< The shift value for the q31_t v[3] reading. */
 	struct {
+		/** Timestamp delta of the reading. Unit is micro seconds. */
 		uint32_t timestamp_delta;
 		union {
+			/**
+			 * 3D vector of the reading represented as an array.
+			 * For SENSING_SENSOR_TYPE_MOTION_ACCELEROMETER_3D and
+			 * SENSING_SENSOR_TYPE_MOTION_UNCALIB_ACCELEROMETER_3D,
+			 * the unit is Gs (gravitational force).
+			 * For SENSING_SENSOR_TYPE_MOTION_GYROMETER_3D, the unit is degrees.
+			 */
 			q31_t v[3];
 			struct {
-				q31_t x;
-				q31_t y;
-				q31_t z;
+				q31_t x; /**< X value of the 3D vector. */
+				q31_t y; /**< Y value of the 3D vector. */
+				q31_t z; /**< Z value of the 3D vector. */
 			};
 		};
-	} readings[1];
+	} readings[1]; /**< Array of readings. */
 };
 
 /**
@@ -86,11 +95,17 @@ struct sensing_sensor_value_3d_q31 {
  * uint32_t version
  */
 struct sensing_sensor_value_uint32 {
+	/** Header of the sensor value data structure. */
 	struct sensing_sensor_value_header header;
 	struct {
+		/** Timestamp delta of the reading. Unit is micro seconds. */
 		uint32_t timestamp_delta;
+		/**
+		 * Value of the reading.
+		 * For SENSING_SENSOR_TYPE_LIGHT_AMBIENTLIGHT, the unit is luxs.
+		 */
 		uint32_t v;
-	} readings[1];
+	} readings[1];      /**< Array of readings. */
 };
 
 /**
@@ -99,15 +114,20 @@ struct sensing_sensor_value_uint32 {
  * q31 version
  */
 struct sensing_sensor_value_q31 {
+	/** Header of the sensor value data structure. */
 	struct sensing_sensor_value_header header;
-	int8_t shift;
+	int8_t shift; /**< The shift value for the q31_t v reading. */
 	struct {
+		/** Timestamp delta of the reading. Unit is micro seconds. */
 		uint32_t timestamp_delta;
+		/**
+		 * Value of the reading.
+		 * For SENSING_SENSOR_TYPE_MOTION_HINGE_ANGLE, the unit is degrees.
+		 */
 		q31_t v;
-	} readings[1];
+	} readings[1];   /**< Array of readings. */
 };
 
-
 /**
  * @}
  */