include: sensing: doc: documentation improvements

- Add missing documentation for the Sensing Subsystem API and complete
  existing docs when it was too terse
- Other grammar/cosmetic improvements

Signed-off-by: Benjamin Cabé <[email protected]>

Author: kartben

include/zephyr/sensing/sensing.h

@@ -32,7 +32,6 @@ extern "C" {
 #endif
 
 /**
- * @struct sensing_sensor_version
  * @brief Sensor Version
  */
 struct sensing_sensor_version {
@@ -48,85 +47,119 @@ struct sensing_sensor_version {
 };
 
 /**
- * @brief Macro to create a sensor version value.
+ * @brief Build a packed @ref sensing_sensor_version value.
  *
+ * @param _major  Major version.
+ * @param _minor  Minor version.
+ * @param _hotfix Hotfix version.
+ * @param _build  Build number.
+ * @return 32-bit packed version value
  */
 #define SENSING_SENSOR_VERSION(_major, _minor, _hotfix, _build)         \
 				(FIELD_PREP(GENMASK(31, 24), _major) |  \
 				 FIELD_PREP(GENMASK(23, 16), _minor) |  \
 				 FIELD_PREP(GENMASK(15, 8), _hotfix) |  \
 				 FIELD_PREP(GENMASK(7, 0), _build))
 
+/**
+ * @name Sensor reporting flags
+ * @{
+ */
 
 /**
- * @brief Sensor flag indicating if this sensor is on event reporting data.
+ * @brief Sensor flag indicating if this sensor is reporting data on event.
  *
  * Reporting sensor data when the sensor event occurs, such as a motion detect sensor reporting
  * a motion or motionless detected event.
+ *
+ * @note Mutually exclusive with \ref SENSING_SENSOR_FLAG_REPORT_ON_CHANGE
  */
 #define SENSING_SENSOR_FLAG_REPORT_ON_EVENT			BIT(0)
 
 /**
- * @brief Sensor flag indicating if this sensor is on change reporting data.
+ * @brief Sensor flag indicating if this sensor is reporting data on change.
  *
  * Reporting sensor data when the sensor data changes.
  *
- * Exclusive with \ref SENSING_SENSOR_FLAG_REPORT_ON_EVENT
+ * @note Mutually exclusive with \ref SENSING_SENSOR_FLAG_REPORT_ON_EVENT
  */
 #define SENSING_SENSOR_FLAG_REPORT_ON_CHANGE			BIT(1)
 
+/** @} */
+
 /**
- * @brief SENSING_SENSITIVITY_INDEX_ALL indicating sensitivity of each data field should be set
+ * @brief Sentinel index meaning "apply to all data fields".
  *
+ * Used with sensitivity configuration where a sensor provides multiple fields in a single sample.
  */
 #define SENSING_SENSITIVITY_INDEX_ALL -1
 
 /**
- * @brief Sensing subsystem sensor state.
+ * @brief Sensor state.
  *
+ * This enumeration defines the possible states of a sensor.
  */
 enum sensing_sensor_state {
 	SENSING_SENSOR_STATE_READY = 0,   /**< The sensor is ready. */
 	SENSING_SENSOR_STATE_OFFLINE = 1, /**< The sensor is offline. */
 };
 
 /**
- * @brief Sensing subsystem sensor config attribute
+ * @brief Sensor configuration attribute.
  *
+ * This enumeration defines the possible attributes of a sensor configuration.
  */
 enum sensing_sensor_attribute {
-	/** The interval attribute of a sensor configuration. */
+	/**
+	 * Reporting interval between samples, in microseconds (us).
+	 *
+	 * See @ref sensing_sensor_config::interval.
+	 */
 	SENSING_SENSOR_ATTRIBUTE_INTERVAL = 0,
-	/** The sensitivity attribute of a sensor configuration. */
+
+	/**
+	 * Per-field sensitivity threshold.
+	 *
+	 * See @ref sensing_sensor_config::sensitivity.
+	 */
 	SENSING_SENSOR_ATTRIBUTE_SENSITIVITY = 1,
-	/** The latency attribute of a sensor configuration. */
+
+	/**
+	 * Maximum batching latency, in microseconds (us).
+	 *
+	 * See @ref sensing_sensor_config::latency.
+	 */
 	SENSING_SENSOR_ATTRIBUTE_LATENCY = 2,
-	/** The maximum number of attributes that a sensor configuration can have. */
+
+	/** Number of supported attributes. */
 	SENSING_SENSOR_ATTRIBUTE_MAX,
 };
 
 /**
- * @brief Define Sensing subsystem sensor handle
+ * @brief Opaque handle to an opened sensor instance.
  *
+ * A valid handle is obtained from @ref sensing_open_sensor or @ref sensing_open_sensor_by_dt and
+ * must be closed with @ref sensing_close_sensor when no longer needed.
  */
 typedef void *sensing_sensor_handle_t;
 
 /**
- * @brief Sensor data event receive callback.
+ * @brief Data event callback signature.
  *
- * @param handle The sensor instance handle.
- * @param buf The data buffer with sensor data.
- * @param context User provided context pointer.
+ * The Sensing subsystem invokes this callback to deliver buffered samples for the opened sensor.
+ *
+ * @param handle  Sensor instance handle passed to @ref sensing_open_sensor.
+ * @param buf     Pointer to a sensor-type-specific sample buffer; see @ref sensing_datatypes and
+ *                @ref sensing_sensor_types.
+ * @param context User context pointer as provided in @ref sensing_callback_list::context.
  */
 typedef void (*sensing_data_event_t)(
 		sensing_sensor_handle_t handle,
 		const void *buf,
 		void *context);
 
 /**
- * @struct sensing_sensor_info
- * @brief Sensor basic constant information
- *
+ * @brief Read-only description of a sensor instance.
  */
 struct sensing_sensor_info {
 	/** Name of the sensor instance */
@@ -153,9 +186,13 @@ struct sensing_sensor_info {
  * @brief Sensing subsystem event callback list
  *
  */
+
+/**
+ * @brief Callback registration for a sensor instance.
+ */
 struct sensing_callback_list {
 	sensing_data_event_t on_data_event; /**< Callback function for a sensor data event. */
-	void *context;                      /**< Associated context with on_data_event */
+	void *context;                      /**< Context that will be passed to the callback. */
 };
 
 /**

include/zephyr/sensing/sensing_sensor.h

@@ -384,7 +384,7 @@ extern const struct rtio_iodev_api __sensing_iodev_api;
 	SENSING_SENSORS_DT_DEFINE(DT_DRV_INST(inst), __VA_ARGS__)
 
 /**
- * @brief Get reporter handles	of a given sensor instance by sensor type.
+ * @brief Get reporter handles of a given sensor instance by sensor type.
  *
  * @param dev The sensor instance device structure.
  * @param type The given type, \ref SENSING_SENSOR_TYPE_ALL to get reporters