include: ec_host_cmd: doxygen improvements

- add some missing docs
- make sure API guarded by Kconfig is showing up in the docs
- show EC Host Command docs in the Device Management group
- re-arrange groups for backends and simulator API

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

Author: kartben

include/zephyr/mgmt/ec_host_cmd/backend.h

@@ -7,11 +7,19 @@
 /**
  * @file
  * @brief Public APIs for Host Command backends that respond to host commands
+ * @ingroup ec_host_cmd_backend
  */
 
 #ifndef ZEPHYR_INCLUDE_MGMT_EC_HOST_CMD_BACKEND_H_
 #define ZEPHYR_INCLUDE_MGMT_EC_HOST_CMD_BACKEND_H_
 
+/**
+ * @brief Interface to EC Host Command backends
+ * @defgroup ec_host_cmd_backend Backends
+ * @ingroup ec_host_cmd_interface
+ * @{
+ */
+
 #include <zephyr/sys/__assert.h>
 #include <zephyr/device.h>
 #include <zephyr/drivers/gpio.h>
@@ -22,20 +30,16 @@
 extern "C" {
 #endif
 
+/**
+ * @brief EC Host Command Backend
+ */
 struct ec_host_cmd_backend {
-	/** API provided by the backed. */
+	/** API provided by the backend. */
 	const struct ec_host_cmd_backend_api *api;
-	/** Context for the backed. */
+	/** Context for the backend. */
 	void *ctx;
 };
 
-/**
- * @brief EC Host Command Interface
- * @defgroup ec_host_cmd_interface EC Host Command Interface
- * @ingroup io_interfaces
- * @{
- */
-
 /**
  * @brief Context for host command backend and handler to pass rx data.
  */
@@ -58,7 +62,7 @@ struct ec_host_cmd_rx_ctx {
  */
 struct ec_host_cmd_tx_buf {
 	/**
-	 * Data to write to the host The buffer is provided by the handler if
+	 * Data to write to the host. The buffer is provided by the handler if
 	 * CONFIG_EC_HOST_CMD_HANDLER_TX_BUFFER_SIZE > 0. Otherwise, the backend should provide
 	 * the buffer on its own and overwrites @a buf pointer and @a len_max
 	 * in the init function.

include/zephyr/mgmt/ec_host_cmd/ec_host_cmd.h

@@ -12,7 +12,7 @@
  * @defgroup ec_host_cmd_interface EC Host Command Interface
  * @since 2.4
  * @version 0.1.0
- * @ingroup io_interfaces
+ * @ingroup device_mgmt
  * @{
  */
 
@@ -72,24 +72,54 @@ enum ec_host_cmd_status {
 	EC_HOST_CMD_MAX = UINT16_MAX /* Force enum to be 16 bits. */
 } __packed;
 
+/**
+ * @brief Host command log levels
+ */
 enum ec_host_cmd_log_level {
-	EC_HOST_CMD_DEBUG_OFF, /* No Host Command debug output */
-	EC_HOST_CMD_DEBUG_NORMAL, /* Normal output mode; skips repeated commands */
-	EC_HOST_CMD_DEBUG_EVERY, /* Print every command */
-	EC_HOST_CMD_DEBUG_PARAMS, /* ... and print params for request/response */
-	EC_HOST_CMD_DEBUG_MODES /* Number of host command debug modes */
+	EC_HOST_CMD_DEBUG_OFF,    /**< No Host Command debug output */
+	EC_HOST_CMD_DEBUG_NORMAL, /**< Normal output mode; skips repeated commands */
+	EC_HOST_CMD_DEBUG_EVERY,  /**< Print every command */
+	EC_HOST_CMD_DEBUG_PARAMS, /**< ... and print params for request/response */
+	EC_HOST_CMD_DEBUG_MODES   /**< Number of host command debug modes */
 };
 
+/**
+ * @brief Host command state
+ */
 enum ec_host_cmd_state {
-	EC_HOST_CMD_STATE_DISABLED = 0,
-	EC_HOST_CMD_STATE_RECEIVING,
-	EC_HOST_CMD_STATE_PROCESSING,
-	EC_HOST_CMD_STATE_SENDING,
+	EC_HOST_CMD_STATE_DISABLED = 0, /**< Host command subsystem is disabled */
+	EC_HOST_CMD_STATE_RECEIVING,    /**< Receiving command data from host */
+	EC_HOST_CMD_STATE_PROCESSING,   /**< Processing received command */
+	EC_HOST_CMD_STATE_SENDING,      /**< Sending response to host */
 };
 
+/**
+ * @brief User callback function type for host command reception
+ *
+ * This callback is invoked after a host command is received and validated
+ * but before command processing begins. It allows user code to perform
+ * custom actions based on the received command.
+ *
+ * @param rx_ctx Pointer to the receive context containing command data
+ * @param user_data User-defined data pointer passed during callback registration
+ */
 typedef void (*ec_host_cmd_user_cb_t)(const struct ec_host_cmd_rx_ctx *rx_ctx, void *user_data);
+
+/**
+ * @brief In-progress callback function type
+ *
+ * This callback is executed asynchronously for commands that return
+ * EC_HOST_CMD_IN_PROGRESS status. It allows long-running operations
+ * to complete in the background.
+ *
+ * @param user_data User-provided data passed to the callback
+ * @return Final status code for the command
+ */
 typedef enum ec_host_cmd_status (*ec_host_cmd_in_progress_cb_t)(void *user_data);
 
+/**
+ * Host command context structure
+ */
 struct ec_host_cmd {
 	struct ec_host_cmd_rx_ctx rx_ctx;
 	struct ec_host_cmd_tx_buf tx;
@@ -138,7 +168,18 @@ struct ec_host_cmd_handler_args {
 	uint16_t output_buf_size;
 };
 
+/**
+ * @brief Host command handler callback function type
+ *
+ * This callback is invoked to process a host command that matches the handler's
+ * command ID and version. The handler processes the incoming command data and
+ * generates a response.
+ *
+ * @param args Pointer to the handler arguments containing command data and buffers
+ * @return Status code indicating the result of command processing
+ */
 typedef enum ec_host_cmd_status (*ec_host_cmd_handler_cb)(struct ec_host_cmd_handler_args *args);
+
 /**
  * @brief Structure use for statically registering host command handlers
  */
@@ -334,13 +375,15 @@ const struct ec_host_cmd *ec_host_cmd_get_hc(void);
 FUNC_NORETURN void ec_host_cmd_task(void);
 #endif
 
-#ifdef CONFIG_EC_HOST_CMD_IN_PROGRESS_STATUS
+#if defined(CONFIG_EC_HOST_CMD_IN_PROGRESS_STATUS) || defined(__DOXYGEN__)
 /**
  * @brief Check if a Host Command that sent EC_HOST_CMD_IN_PROGRESS status has ended.
  *
  * A Host Command that sends EC_HOST_CMD_IN_PROGRESS status doesn't send a final result.
  * The final result can be get with the ec_host_cmd_send_in_progress_status function.
  *
+ * @kconfig_dep{CONFIG_EC_HOST_CMD_IN_PROGRESS_STATUS}
+ *
  * @retval true if the Host Command endded
  */
 bool ec_host_cmd_send_in_progress_ended(void);
@@ -354,6 +397,8 @@ bool ec_host_cmd_send_in_progress_ended(void);
  *
  * Saving status of Host Commands that send response data is not supported.
  *
+ * @kconfig_dep{CONFIG_EC_HOST_CMD_IN_PROGRESS_STATUS}
+ *
  * @retval The final status or EC_HOST_CMD_UNAVAILABLE if not available.
  */
 enum ec_host_cmd_status ec_host_cmd_send_in_progress_status(void);
@@ -367,6 +412,8 @@ enum ec_host_cmd_status ec_host_cmd_send_in_progress_status(void);
  * ec_host_cmd_send_in_progress_status function. The ec_host_cmd_send_in_progress_ended function
  * can be used to check if the callback has ended.
  *
+ * @kconfig_dep{CONFIG_EC_HOST_CMD_IN_PROGRESS_STATUS}
+ *
  * @param[in] cb          A callback to be called after returning from a command handler.
  * @param[in] user_data   User data to be passed to the callback.
  *

include/zephyr/mgmt/ec_host_cmd/simulator.h

@@ -4,13 +4,21 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-#ifndef ZEPHYR_INCLUDE_MGMT_EC_HOST_CMD_SIMULATOR_H_
-#define ZEPHYR_INCLUDE_MGMT_EC_HOST_CMD_SIMULATOR_H_
-
 /**
  * @file
  * @brief Header for commands to interact with the simulator outside of normal
  *        device interface.
+ * @ingroup ec_host_cmd_simulator
+ */
+
+#ifndef ZEPHYR_INCLUDE_MGMT_EC_HOST_CMD_SIMULATOR_H_
+#define ZEPHYR_INCLUDE_MGMT_EC_HOST_CMD_SIMULATOR_H_
+
+/**
+ * @brief Interface to EC Host Command Simulator
+ * @defgroup ec_host_cmd_simulator Simulator
+ * @ingroup ec_host_cmd_interface
+ * @{
  */
 
 /* For ec_host_cmd_backend_api_send function pointer type */
@@ -45,4 +53,8 @@ void ec_host_cmd_backend_sim_install_send_cb(ec_host_cmd_backend_api_send cb,
  */
 int ec_host_cmd_backend_sim_data_received(const uint8_t *buffer, size_t len);
 
+/**
+ * @}
+ */
+
 #endif /* ZEPHYR_INCLUDE_MGMT_EC_HOST_CMD_SIMULATOR_H_ */