Improve code style and comments

stm-firmware/include/reflow-controller/settings/settings-sd-card.h

@@ -24,6 +24,13 @@
 #include <stdbool.h>
 #include <reflow-controller/settings/settings.h>
 
+/**
+ * @brief Save the calibration to the SD card
+ * @param sens_deviation Sensitivity deviation from nomila sensitivity (1)
+ * @param offset Offset
+ * @param active Calibration is active. If false, the calibration will be deleted from SD card
+ * @return 0 if successful
+ */
 int sd_card_settings_save_calibration(float sens_deviation, float offset, bool active);
 
 /**
@@ -34,6 +41,13 @@ int sd_card_settings_save_calibration(float sens_deviation, float offset, bool a
  */
 int sd_card_settings_try_load_calibration(float *sens_deviation, float *offset);
 
+/**
+ * @brief Load the PID parameters from @ref SETTINGS_PID_PARAMETER_FILE
+ * @param settings The PID settings
+ * @return Load result.
+ * @note This function is currently not used for the temperature profiles. They implement the PID parameters directy
+ * inside the profile
+ */
 enum settings_load_result sd_card_settings_load_pid_oven_parameters(struct oven_pid_settings *settings);
 
 #endif /* __SETTINGS_SETTINGS_SD_CARD_H__ */

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

@@ -24,20 +24,26 @@
 
 #include <stdbool.h>
 
+/**
+ * @brief Settings for the PID controller that are stored in the config file
+ */
 struct oven_pid_settings {
-	float kd;
-	float kp;
-	float ki;
-	float kd_tau;
-	float t_sample;
-	float max_integral;
+	float kd; /**< @brief Derivate term */
+	float kp; /**< @brief Proportional term */
+	float ki; /**< @brief Integral term */
+	float kd_tau; /**< @brief Time constant of the derivate term's low pass filter */
+	float t_sample; /**< @brief Sampling time in seconds. @warning The loading function expects the file to hold a ms value */
+	float max_integral; /**< @brief Maximum value of the intgral term */
 };
 
+/**
+ * @brief Results of a setting loading
+ */
 enum settings_load_result {
-	SETT_LOAD_SUCCESS = 0,
-	SETT_LOAD_FILE_NOT_FOUND,
-	SETT_LOAD_ERR,
-	SETT_LOAD_DISK_ERR
+	SETT_LOAD_SUCCESS = 0, /**< @brief Setting loaded successfully */
+	SETT_LOAD_FILE_NOT_FOUND, /**< @brief File not found. This is only used by Settings on the SD card */
+	SETT_LOAD_ERR, /**< @brief Generic loading error */
+	SETT_LOAD_DISK_ERR, /**< @brief Disk access failure during loading */
 };
 
 #define SETTINGS_PID_PARAMETER_FILE "pid.conf"
@@ -50,14 +56,49 @@ enum settings_load_result {
  */
 int settings_save_calibration(float sens_deviation, float offset, bool active);
 
+/**
+ * @brief Load the calibration
+ *
+ * If an EEPROM is present, it is first tried to be retrieved from EEPROM.
+ * If there is no EEPROM or there is no valid data inside, it is tried to be loaded from SD card.
+ *
+ * @param sens_dev Sensiotivity deviation
+ * @param offset Offset
+ * @return 0 if successful and calibration valid
+ */
 int settings_load_calibration(float *sens_dev, float *offset);
 
+/**
+ * @brief Load PID overn parameters from file on SD card. This function is not implemented for EEPROM.
+ * @param settings settings
+ * @return Load result
+ */
 enum settings_load_result settings_load_pid_oven_parameters(struct oven_pid_settings *settings);
 
+/**
+ * @brief read the configured overtemperature limit
+ * @param[out] over_temp_limit Overtemperature limit in degrees Celsius
+ * @return Load result
+ */
 enum settings_load_result settings_load_overtemp_limit(float *over_temp_limit);
 
+/**
+ * @brief Save the overtemperature limit
+ * @param over_temp_limit Limit in degrees Celsius
+ * @param active Overtemperature limit active. If false: The config is delted and the controller uses its default limit
+ * @return 0 if successful
+ */
 int settings_save_overtemp_limit(float over_temp_limit, bool active);
 
+/**
+ * @brief Setup the settings module
+ *
+ * This function has to be called before performing any settings operations.
+ * It checks if an EEPTROM is connected and sets the appropriate settings storage in this case.
+ *
+ * EEPROM storage will only be available for HW versions > 1.3. Some functions require an EEPROM because the counterpart
+ * on the SD card is not defined. These functions will fail without an EEPROM.
+ */
 void settings_setup(void);
 
 #endif /* __SETTINGS_SETTINGS_H__ */

stm-firmware/include/reflow-controller/settings/spi-eeprom.h

@@ -24,19 +24,59 @@
 #include <stdint.h>
 #include <stdbool.h>
 
-
+/**
+ * @brief Initialize the SPI for the eeprom.
+ * @return 0 if succesful
+ */
 int spi_eeprom_init();
 
+/**
+ * @brief Uninitialize the SPI EEPROM
+ */
 void spi_eeprom_deinit();
 
+/**
+ * @brief Read from SPI EEPROM
+ * @param addr address to read from
+ * @param rx_buff buffer to write data to
+ * @param count Amount of bytes to read
+ * @return  0 if successful
+ */
 int spi_eeprom_read(uint32_t addr, uint8_t *rx_buff, uint32_t count);
 
+/**
+ * @brief Check if the EEPROM is currently performing a write and therefore cannot serve other requests
+ * @return true: Write in Progress, false: No write active
+ */
 bool spi_eeprom_write_in_progress(void);
 
+/**
+ * @brief Write data to the EEPROM
+ * @param addr Address to write to
+ * @param data Data to write
+ * @param count Amount of bytes to write
+ * @return 0 if successful
+ * @note The page handling of the EEPROM is done internally. When using this function there is no need to worry about
+ * the 16 byte page boundaries of the EEPROM
+ */
 int spi_eeprom_write(uint32_t addr, const uint8_t *data, uint32_t count);
 
+/**
+ * @brief Read the status register of the EEPROM
+ * @return status register
+ */
 uint8_t spi_eeprom_read_status_reg(void);
 
+/**
+ * @brief Check if an EEPROM is connected to the SPI.
+ *
+ * This is done by trying to set the write enable latch in the status register and reading it back.
+ * After it has been set, it is immediately reset.
+ *
+ * If it can't be read back, no EEPROM is connected
+ *
+ * @return true: EEPROM is connected, false: No (compatible) EEPROM found
+ */
 bool spi_eeprom_check_connected(void);
 
 #endif /* __SETTINGS_SPI_EEPROM_H__ */