From 66c866465f574dee2abbe1a9738148f2d840d154 Mon Sep 17 00:00:00 2001
From: Wojciech Pietraszewski <wojciech.pietraszewski@codecoup.pl>
Date: Fri, 30 Jun 2023 16:23:06 +0200
Subject: [PATCH] host/dtm: add doxygen comments for the header file

Add missing doxygen comments.
---
 nimble/host/include/host/ble_dtm.h | 77 ++++++++++++++++++++++++++++++
 1 file changed, 77 insertions(+)

diff --git a/nimble/host/include/host/ble_dtm.h b/nimble/host/include/host/ble_dtm.h
index e340a3069a..cd01a23b70 100644
--- a/nimble/host/include/host/ble_dtm.h
+++ b/nimble/host/include/host/ble_dtm.h
@@ -25,25 +25,102 @@
 extern "C" {
 #endif
 
+/**
+ * @file ble_dtm.h
+ *
+ * @brief DTM (Direct Test Mode)
+ *
+ * This header file provides the interface and data structures for working with
+ * the Direct Test Mode (DTM) functionality in a BLE (Bluetooth Low Energy) host.
+ * DTM allows for testing and validation of the BLE radio performance by enabling
+ * custom transmission and reception of data packets.
+ *
+ * @defgroup bt_host_dtm Bluetooth Host Direct Test Mode
+ * @ingroup bt_host
+ * @{
+ */
+
+/**
+ * @struct ble_dtm_rx_params
+ * @brief Parameters for DTM RX test.
+ *
+ * This structure represents the parameters for a Direct Test Mode (DTM) receiver test.
+ */
 struct ble_dtm_rx_params {
+    /** The channel to use for the RX test. */
     uint8_t channel;
+
+    /** The PHY to use for the RX test. */
     uint8_t phy;
+
+    /** The modulation index to use for the RX test. */
     uint8_t modulation_index;
 };
 
+/**
+ * @brief Start a Direct Test Mode (DTM) receiver test.
+ *
+ * This function starts a DTM RX test with the provided parameters.
+ *
+ * @param params                The parameters for the DTM RX test.
+ *
+ * @return                      0 on success;
+ *                              A non-zero value on failure.
+ */
 int ble_dtm_rx_start(const struct ble_dtm_rx_params *params);
 
+/**
+ * @struct ble_dtm_tx_params
+ * @brief Parameters for DTM TX test.
+ *
+ * This structure represents the parameters for a Direct Test Mode (DTM) transmitter test.
+ */
 struct ble_dtm_tx_params {
+    /** The channel to use for the TX test. */
     uint8_t channel;
+
+    /** The length of the data for the TX test. */
     uint8_t test_data_len;
+
+    /** The payload to use for the TX test. */
     uint8_t payload;
+
+    /** The PHY to use for the TX test. */
     uint8_t phy;
 };
+
+/**
+ * @brief Start a Direct Test Mode (DTM) transmitter test.
+ *
+ * This function starts a DTM TX test with the provided parameters.
+ *
+ * @param params                The parameters for the DTM TX test.
+ *
+ * @return                      0 on success;
+ *                              A non-zero value on failure.
+ */
 int ble_dtm_tx_start(const struct ble_dtm_tx_params *params);
 
+/**
+ * @brief Stops a Direct Test Mode (DTM) test and retrieves the number of transmitted packets.
+ *
+ * This function sends a command to the Bluetooth controller to stop the currently running DTM test.
+ * It retrieves the number of packets transmitted during the test and stores it in the provided `num_packets` variable.
+ *
+ * @param num_packets           Pointer to a `uint16_t` variable to store the number of transmitted packets.
+ *                              If an error occurs, the value will be set to 0.
+ *
+ * @return                      0 on success;
+ *                              A non-zero value on failure.
+ */
 int ble_dtm_stop(uint16_t *num_packets);
 
 #ifdef __cplusplus
 }
 #endif
+
+/**
+ * @}
+ */
+
 #endif