From 8c0cfa4993f81e76c74d746ae879f7c1b8dbae2a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Mario=20H=C3=BCttel?= <mario.huettel@gmx.net>
Date: Sat, 22 May 2021 17:02:37 +0200
Subject: [PATCH] Doxygen headers

---
 .../include/reflow-controller/digio.h         | 112 +++++++++++++++++-
 .../temp-profile/temp-profile-executer.c      |   3 +
 2 files changed, 113 insertions(+), 2 deletions(-)

diff --git a/stm-firmware/include/reflow-controller/digio.h b/stm-firmware/include/reflow-controller/digio.h
index 47d18f3..a0cf259 100644
--- a/stm-firmware/include/reflow-controller/digio.h
+++ b/stm-firmware/include/reflow-controller/digio.h
@@ -18,6 +18,11 @@
  * If not, see <http://www.gnu.org/licenses/>.
  */
 
+/**
+ * @addtogroup digio
+ * @{
+ */
+
 #ifndef __DIGIO_H__
 #define __DIGIO_H__
 
@@ -25,10 +30,22 @@
 #include <stdint.h>
 #include <helper-macros/helper-macros.h>
 
+/**
+ * @brief Port the digital I/Os are located in
+ */
 #define DIGIO_PORT GPIOB
+
+/**
+ * @brief Reset and clock control bit mask to enable clock of @ref DIGIO_PORT
+ */
 #define DIGIO_RCC_MASK RCC_AHB1ENR_GPIOBEN
+
+/**
+ * @brief List of the pins used by the digio module
+ */
 #define DIGIO_PINS 4,5,6,7
 
+
 #if defined(DEBUGBUILD) || defined(UART_ON_DEBUG_HEADER)
 #define DIGIO_INOUT_DEFAULT 0,0,0,0
 #define DIGIO_ALTFUNC_DEFAULT 0,0,0,0
@@ -37,33 +54,124 @@
 #define DIGIO_ALTFUNC_DEFAULT 0,0,7,7
 #endif
 
+/**
+ * @brief The port, the loudspeaker is connected to
+ */
 #define BEEPER_PORT GPIOB
+
+/**
+ * @brief The RCC mask for @ref BEEPER_PORT
+ */
 #define BEEPER_RCC_MASK RCC_AHB1ENR_GPIOBEN
 
-
+/**
+ * @brief Enable all clocks and setup pins in default setting
+ * @warning This function uses @ref rcc_manager_enable_clock to enable the clocks. Therefore, it must not be called
+ * multiple times.
+ */
 void digio_setup_default_all(void);
 
+/**
+ * @brief Set up a DIGIO pin.
+ *
+ * Set up a digital IO pin config. For the index association see the @ref DIGIO_PINS table.
+ *
+ * @param num DIGIO number starting with 0
+ * @param in_out In: 0, Out 1, alternate function: 2
+ * @param alt_func Alternate function to set. Consult datasheet of STM32F407
+ */
 void digio_setup_pin(uint8_t num, uint8_t in_out, uint8_t alt_func);
+
+/**
+ * @brief Set a digio output port
+ * @param num Digio channel number
+ * @param val Value: 0 or 1.
+ */
 void digio_set(uint8_t num, int val);
+
+/**
+ * @brief Read the state of a digio channel
+ * @param num Channel number
+ * @return digital pin level.
+ */
 int digio_get(uint8_t num);
 
+/**
+ * @brief Port the LEDs are connected to
+ */
 #define LED_PORT GPIOB
+
+/**
+ * @brief RCC mask to enable clock for @ref LED_PORT
+ */
 #define LED_RCC_MASK RCC_AHB1ENR_GPIOBEN
+
+/**
+ * @brief Pin list on @ref LED_PORT that are connected to LEDs
+ */
 #define LED_PINS 2,3
 
+/**
+ * @brief Set up the LED Port
+ */
 void led_setup(void);
+
+/**
+ * @brief Set the LED status
+ * @param num LED number
+ * @param val Value: 1 on, 0 off.
+ */
 void led_set(uint8_t num, int val);
+
+/**
+ * @brief Get the state of a LED
+ * @param num LED number
+ * @return Stateof the LED: 0 off, 1 on; -1 in case of an error
+ */
 int led_get(uint8_t num);
 
+/**
+ * @brief Port to use for the loudpseaker
+ */
 #define LOUDSPEAKER_PORT GPIOB
+
+/**
+ * @brief RCC mask for @ref LOUDSPEAKER_PORT
+ */
 #define LOUDSPEAKER_RCC_MASK RCC_AHB1ENR_GPIOBEN
+
+/**
+ * @brief Pin on @ref LOUDSPEAKER_PORT the speaker is cnnected to
+ */
 #define LOUDSPEAKER_PIN 1
+
+/**
+ * @brief The loudpseaker requires a frequncy signal instead of a simple on/off signal.
+ */
 #define LOUDSPEAKER_MULTIFREQ 1
+
+/**
+ * @brief Defautl timer relaod for the frequency of the speaker. Only relevant if @ref LOUDSPEAKER_MULTIFREQ is 1.
+ */
 #define LOUDSPEAKER_MULTIFREQ_DEFAULT 9
 
+/**
+ * @brief Setup the loudspeaker
+ */
 void loudspeaker_setup(void);
+
+/**
+ * @brief Set the loudspeaker value
+ * @param val Value
+ */
 void loudspeaker_set(uint16_t val);
+
+/**
+ * @brief Get current value of the loadspeaker
+ * @return Value
+ */
 uint16_t loudspeaker_get(void);
 
-
 #endif /* __DIGIO_H__ */
+
+/** @} */
diff --git a/stm-firmware/temp-profile/temp-profile-executer.c b/stm-firmware/temp-profile/temp-profile-executer.c
index f701320..363c4c7 100644
--- a/stm-firmware/temp-profile/temp-profile-executer.c
+++ b/stm-firmware/temp-profile/temp-profile-executer.c
@@ -168,6 +168,9 @@ static bool cmd_ramp(struct pl_command *cmd, bool cmd_continue)
 	return ret;
 }
 
+/**
+ * @brief Try to acknowledge all set flags.
+ */
 static void cmd_ack_flags(void)
 {
 	uint32_t flag_cnt;