Improve doxygen comments in code.

stm-firmware/include/reflow-controller/digio.h

@@ -146,7 +146,7 @@ int led_get(uint8_t num);
 #define LOUDSPEAKER_PIN 1
 
 /**
- * @brief The loudpseaker requires a frequncy signal instead of a simple on/off signal.
+ * @brief The loudpseaker requires a frequency signal instead of a simple on/off signal.
  */
 #define LOUDSPEAKER_MULTIFREQ 1
 
@@ -162,7 +162,14 @@ void loudspeaker_setup(void);
 
 /**
  * @brief Set the loudspeaker value
- * @param val Value
+ *
+ * Zero turns off the beeper. 1 is a special value
+ * and will set the @ref LOUDSPEAKER_MULTIFREQ_DEFAULT value.
+ *
+ * If @ref LOUDSPEAKER_MULTIFREQ is 0, then no actual frequency is produced.
+ * Instead any @p val unequal to zero turns the output pin high and 0 will turn it low.
+ *
+ * @param val Value.
  */
 void loudspeaker_set(uint16_t val);
 

stm-firmware/include/reflow-controller/main-cycle-counter.h

@@ -18,15 +18,34 @@
 * If not, see <http://www.gnu.org/licenses/>.
 */
 
+/**
+ * @defgroup main-cycle-counter Main Cycle Counter
+ * The main cycle counter is incremented after every loop run of the main loop in main.c
+ * @{
+ */
+
 #ifndef __MAIN_CYCLE_COUNTER_H__
 #define __MAIN_CYCLE_COUNTER_H__
 
 #include <stdint.h>
 
+/**
+ * @brief Initialize/Reset the main cycle counter to 0.
+ * This function can be called multiple times.
+ */
 void main_cycle_counter_init(void);
 
+/**
+ * @brief Increment the main cycle counter by 1
+ */
 void main_cycle_counter_inc(void);
 
+/**
+ * @brief Get the current main cycle counter value
+ * @return Value
+ */
 uint64_t main_cycle_counter_get(void);
 
 #endif /* __MAIN_CYCLE_COUNTER_H__ */
+
+/** @} */

stm-firmware/include/reflow-controller/oven-driver.h

@@ -21,32 +21,93 @@
 #ifndef __OVEN_DRIVER_H__
 #define __OVEN_DRIVER_H__
 
+/**
+ * @defgroup oven-driver Oven SSR Driver and PID Controller
+ * @{
+ */
+
 #include <stdint.h>
 #include <stdbool.h>
 #include <reflow-controller/pid-controller.h>
 
-enum oven_pid_status {OVEN_PID_DEACTIVATED,
-		      OVEN_PID_RUNNING,
-		      OVEN_PID_ABORTED};
+/**
+ * @brief Status of the PID controlling the oven
+ */
+enum oven_pid_status {
+	OVEN_PID_DEACTIVATED, /**< @brief The PID of the oven is deactivated. */
+	OVEN_PID_RUNNING, /**< @brief The PID of the oven is currently active and running. */
+	OVEN_PID_ABORTED, /**< @brief The PID of the oven has been aborted due to an error and is not running. */
+};
 
+/**
+ * @brief Initialize the oven driver.
+ *
+ * This will initialize the Timer for the PWM output to the SSR.
+ * If the hardware revision is >= v1.3 the SSR safety enable line will also be initialized.
+ */
 void oven_driver_init(void);
 
+/**
+ * @brief Set a power level on the oven control output
+ * @param power Power level between 0 to 100
+ * @note This will not actually set the output. For this, @ref oven_driver_apply_power_level() has to be called.
+ * It will be called in the main loop.
+ */
 void oven_driver_set_power(uint8_t power);
 
+/**
+ * @brief Disable the oven driver.
+ *
+ * This shuts down the oven driver timer and the corresponding clocks.
+ */
 void oven_driver_disable(void);
 
+/**
+ * @brief Initialize the PID controller for the oven output
+ * @param PID controller holding the settings
+ */
 void oven_pid_init(struct pid_controller *controller_to_copy);
 
+/**
+ * @brief Handle the PID controller.
+ * This must be called cyclically. When the sampling period has passed, the function will process the PT1000
+ * resistance and do a PID cycluilation for this sample.
+ * @note This function must be called with a frequency greater or equal to the PID's sampling frequency
+ */
 void oven_pid_handle(void);
 
+/**
+ * @brief Stop the oven PID controller
+ */
 void oven_pid_stop(void);
 
+/**
+ * @brief Abort the oven PID controller. This is the same as oven_pid_stop() but will set the abort flag.
+ * @note this function is called by the safety controller to disable the PID controller in case of an error.
+ */
 void oven_pid_abort(void);
 
+/**
+ * @brief Set the target temperature of the PID controller.
+ * @param temp
+ */
 void oven_pid_set_target_temperature(float temp);
 
+/**
+ * @brief Output the power level currently configured to the SSR.
+ *
+ * This function is separated from oven_driver_set_power() because it is called in the main loop after the
+ * safety controller has run. This ensures, that if the safety controller decides to stop the PID no glitch makes it
+ * out to the SSR.
+ */
 void oven_driver_apply_power_level(void);
 
+/**
+ * @brief Get the current status of the oven's PID controller
+ * @return
+ */
 enum oven_pid_status oven_pid_get_status(void);
 
+/** @} */
+
 #endif /* __OVEN_DRIVER_H__ */