include: sensing: doc: documentation improvements

- Move sensing documentation in the "OS Services" group
  and clean up group declarations
- 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

doc/services/sensing/index.rst

@@ -246,7 +246,4 @@ See the example :zephyr_file:`samples/subsys/sensing/simple/boards/native_sim.ov
 API Reference
 *************
 
-.. doxygengroup:: sensing_sensor_types
-.. doxygengroup:: sensing_datatypes
 .. doxygengroup:: sensing_api
-.. doxygengroup:: sensing_sensor

include/zephyr/sensing/sensing.h

@@ -8,32 +8,26 @@
 #define ZEPHYR_INCLUDE_SENSING_H_
 
 /**
- * @defgroup sensing Sensing
- * @defgroup sensing_api Sensing Subsystem API
- * @ingroup sensing
- * @defgroup sensing_sensor_types Sensor Types
- * @ingroup sensing
- * @defgroup sensing_datatypes Data Types
- * @ingroup sensing
+ * @defgroup sensing_api Sensing
+ * @brief High-level sensor framework.
+ * @ingroup os_services
+ *
+ * The Sensing subsystem provides a high-level API for applications to discover sensors, open sensor
+ * instances, configure reporting behavior, and receive sampled data via callbacks.
+ * For low-level sensor access, see @ref sensor_interface.
+ *
+ * @{
  */
 
 #include <zephyr/sensing/sensing_datatypes.h>
 #include <zephyr/sensing/sensing_sensor_types.h>
 #include <zephyr/device.h>
 
-/**
- * @brief Sensing Subsystem API
- * @addtogroup sensing_api
- * @{
- */
-
 #ifdef __cplusplus
 extern "C" {
 #endif
 
-
 /**
- * @struct sensing_sensor_version
  * @brief Sensor Version
  */
 struct sensing_sensor_version {
@@ -49,85 +43,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 */
@@ -154,9 +182,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_datatypes.h

@@ -11,14 +11,15 @@
 #include <zephyr/dsp/types.h>
 
 /**
- * @brief Data Types
- * @addtogroup sensing_datatypes
+ * @defgroup sensing_datatypes Data Types
+ * @ingroup sensing_api
+ * @brief Sensor data structures used by the sensing subsystem
+ *
  * @{
  */
 
 /**
- * @struct sensing_sensor_value_header
- * @brief sensor value header
+ * @brief Common header for all sensor value payloads.
  *
  * Each sensor value data structure should have this header
  *

include/zephyr/sensing/sensing_sensor.h

@@ -13,15 +13,9 @@
 #include <zephyr/sensing/sensing.h>
 
 /**
- * @defgroup sensing_sensor Sensing Sensor API
- * @ingroup sensing
- * @defgroup sensing_sensor_callbacks Sensor Callbacks
- * @ingroup sensing_sensor
- */
-
-/**
- * @brief Sensing Sensor API
- * @addtogroup sensing_sensor
+ * @brief Interfaces to manipulate sensors in the sensing subsystem
+ * @defgroup sensing_sensor Sensors (Sensing)
+ * @ingroup sensing_api
  * @{
  */
 
@@ -390,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

include/zephyr/sensing/sensing_sensor_types.h

@@ -8,14 +8,15 @@
 #define ZEPHYR_INCLUDE_SENSING_SENSOR_TYPES_H_
 
 /**
- * @brief Sensor Types Definition
+ * @defgroup sensing_sensor_types Sensor Types (Sensing)
+ * @ingroup sensing_api
+ *
+ * @brief Sensor type identifiers used by the sensing subsystem.
  *
  * Sensor types definition followed HID standard.
  * https://usb.org/sites/default/files/hutrr39b_0.pdf
  *
  * TODO: will add more types
- *
- * @addtogroup sensing_sensor_types
  * @{
  */