Improve comments and doxygen headers

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

@@ -23,7 +23,6 @@
  * @{
  */
 
-
 #ifndef __SAFETY_CONTROLLER_H__
 #define __SAFETY_CONTROLLER_H__
 
@@ -32,30 +31,39 @@
 #include <stdint.h>
 #include <stddef.h>
 
-enum analog_monitor_status {ANALOG_MONITOR_OK = 0,
-			    ANALOG_MONITOR_ERROR,
-			    ANALOG_MONITOR_INACTIVE,
-			    ANALOG_MONITOR_OVER,
-			    ANALOG_MONITOR_UNDER};
+/**
+ * @brief State of an analog monitor
+ */
+enum analog_monitor_status {ANALOG_MONITOR_OK = 0,	/**< @brief Monitor set up and ok */
+			    ANALOG_MONITOR_ERROR,	/**< @brief An internal error occured */
+			    ANALOG_MONITOR_INACTIVE,	/**< @brief Monitor inactive. Reading is not valid */
+			    ANALOG_MONITOR_OVER,	/**< @brief Value too high */
+			    ANALOG_MONITOR_UNDER};	/**< @brief Value too low */
 
+/**
+ * @brief Info structure describing an analog monitor
+ */
 struct analog_monitor_info {
-	float value;
-	float min;
-	float max;
-	enum analog_monitor_status status;
-	uint64_t timestamp;
-};
-
-struct timing_monitor_info {
-	uint64_t last_run;
-	uint64_t min;
-	uint64_t max;
-	bool enabled;
-	uint64_t delta;
+	float value;	/**< @brief Current analog value */
+	float min;	/**< @brief Minumum value allowed */
+	float max;	/**< @brief Maximum value allowed */
+	enum analog_monitor_status status; /**< @brief Current monitor status */
+	uint64_t timestamp; /**< @brief ms timestamp when @ref analog_monitor_info::value was taken. */
 };
 
 /**
- * @brief Initialize the safety controller
+ * @brief Info structure describing a timing monitor
+ */
+struct timing_monitor_info {
+	uint64_t last_run;	/**< @brief Timestamp, when the monitor was last triggered */
+	uint64_t min;		/**< @brief Minimum delay between two activations in ms */
+	uint64_t max;		/**< @brief Maximum delay between two activations in ms */
+	bool enabled;		/**< @brief Monitor enabled */
+	uint64_t delta;		/**< @brief Last delta between two activations */
+};
+
+/**
+ * @brief Initialize the safety controller.
  *
  * After a call to this function the controller is iniotlaized and the watchdog is set up.
  * You have to call safety_controller_handle
@@ -70,42 +78,177 @@ void safety_controller_init();
  */
 int safety_controller_handle();
 
+/**
+ * @brief Report one or multiple errors to the safety controller
+ *
+ * When passing multipe error glags, the flags have to be ORed together.
+ *
+ * @param flag Error flag to report
+ * @return 0 if successful.
+ */
 int safety_controller_report_error(enum safety_flag flag);
 
+/**
+ * @brief Report one or multiple error flags with a key.
+ *
+ * When setting a \p key on an error flag. The error flag can only be cleared,
+ * by passing the same key value to the @ref safety_controller_ack_flag_with_key function.
+ *
+ * @param flag Error flag to report
+ * @param key Key
+ * @return 0 if successful
+ */
 int safety_controller_report_error_with_key(enum safety_flag flag, uint32_t key);
 
+/**
+ * @brief Report timing to a timing monitor.
+ * @param monitor Monitor to report
+ */
 void safety_controller_report_timing(enum timing_monitor monitor);
 
+/**
+ * @brief Report an analog value to an analog value monitor
+ * @param monitor Monitor to report
+ * @param value Analog value
+ */
 void safety_controller_report_analog_value(enum analog_value_monitor monitor, float value);
 
+/**
+ * @brief Enable or disable a timing monitor.
+ * @param monitor Monitor to enable
+ * @param enable State to set the monitor to.
+ * @return 0 if successful.
+ */
 int safety_controller_enable_timing_mon(enum timing_monitor monitor, bool enable);
 
+/**
+ * @brief Get the value of an analog monitor.
+ * @param monitor Monitor to get value from
+ * @param[out] value The analog value
+ * @returns Status of the analog monitor. \p value only valid, if return value does not indicate an internal error,
+ *          or an inactive monitor.
+ */
 enum analog_monitor_status safety_controller_get_analog_mon_value(enum analog_value_monitor monitor, float *value);
 
+/**
+ * @brief Get error flag state and optionally acknowledge the flag
+ *
+ * If the flag is persistent, it cannot be ack'ed. In this case this function
+ * does not return an error code.
+ *
+ * @param flag Error flag
+ * @param[out] status state of the flag.
+ * @param try_ack Try to ack the flag. This might fail, if the flag is persistent.
+ * @return 0 if successful.
+ */
 int safety_controller_get_flag(enum safety_flag flag, bool *status, bool try_ack);
 
+/**
+ * @brief Ack an error flag
+ * @param flag Error flag to ack
+ * @return 0 if successful, -2 if flag is persistent or keyed. All other values: Errors
+ */
 int safety_controller_ack_flag(enum safety_flag flag);
 
+/**
+ * @brief Acknowledge error flag with a key
+ * @param flag Error flag
+ * @param key Key
+ * @return 0 if successful, -2 if flag is persistent or key wrong. All other values: Errors
+ */
 int safety_controller_ack_flag_with_key(enum safety_flag flag, uint32_t key);
 
+/**
+ * @brief Get an ored status of multiple flags.
+ * @param mask Flags to check
+ * @return True if errors. False if no errors.
+ */
 bool safety_controller_get_flags_by_mask(enum safety_flag mask);
 
+/**
+ * @brief Get the count of error flags
+ * @return Error flag count
+ */
 uint32_t safety_controller_get_flag_count();
 
+/**
+ * @brief Get the count of analog monitors
+ * @return Analog monitor count
+ */
 uint32_t safety_controller_get_analog_monitor_count();
 
+/**
+ * @brief Get an error flag's name by its index.
+ *
+ * The name of the flag will be cropped, if the buffersize is too small.
+ * Paramter \p buffsize may not be zero.
+ *
+ * @param index 0 based index.
+ * @param[out] buffer Buffer to write the name to.
+ * @param buffsize Buffer size. This has to be big enough to hold the name and the \0-terminator
+ * @return 0 of successful
+ */
 int safety_controller_get_flag_name_by_index(uint32_t index, char *buffer, size_t buffsize);
 
+/**
+ * @brief Get the safety flag by its internal index.
+ * @param index 0 based index.
+ * @param[out] status Current flag state. May be NULL.
+ * @param[out] flag_enum Flag enum used in SW. May be NULL.
+ * @return 0 if successful; else: negative
+ */
 int safety_controller_get_flag_by_index(uint32_t index, bool *status, enum safety_flag *flag_enum);
 
+/**
+ * @brief Get an analog monitor info by the monitor's index
+ * @param index 0 based index
+ * @param[out] info Info structure.
+ * @return 0 if successful.
+ *         -1001, if \p index out of range
+ *         -1002, if \p info is NULL
+ */
 int safety_controller_get_analog_mon_by_index(uint32_t index, struct analog_monitor_info *info);
 
+/**
+ * @brief Get the name of an analog monitor by its index
+ *
+ * The buffer has to be large enough to hold the name plus a null terminator.
+ * If the buffer is not large enough, The name will be cropped.
+ * Parameter \p buffsize may not be zero.
+ *
+ * @param index 0 based index
+ * @param buffer Buffer to write name to
+ * @param buffsize Buffer size
+ * @return
+ */
 int safety_controller_get_analog_mon_name_by_index(uint32_t index, char *buffer, size_t buffsize);
 
+/**
+ * @brief Get timing monitor information by index
+ * @param index 0 based index
+ * @param[out] info Info
+ * @return 0 if successful
+ */
 int safety_controller_get_timing_mon_by_index(uint32_t index, struct timing_monitor_info *info);
 
+/**
+ * @brief Get the name of a timing monitor by its index
+ *
+ * The buffer has to be large enough to hold the name plus a null terminator.
+ * If the buffer is not large enough, The name will be cropped.
+ * Parameter \p buffsize may not be zero.
+ *
+ * @param index 0 based index
+ * @param buffer Buffer to write name to.
+ * @param buffsize Buffer size
+ * @return 0 if successful
+ */
 int safety_controller_get_timing_mon_name_by_index(uint32_t index, char *buffer, size_t buffsize);
 
+/**
+ * @brief Get the count of timing monitors
+ * @return Timing monitor count
+ */
 uint32_t safety_controller_get_timing_monitor_count();
 
 #endif /* __SAFETY_CONTROLLER_H__ */

stm-firmware/include/reflow-controller/safety/stack-check.h

@@ -37,6 +37,10 @@ int32_t stack_check_get_usage();
  */
 int32_t stack_check_get_free();
 
+/**
+ * @brief Check if the current free stack space is bigger than @ref STACK_CHECK_MIN_HEAP_GAP
+ * @return 0: enough space available, -1: stack space low
+ */
 static inline int stack_check_collision()
 {
 	int ret = 0;
@@ -49,6 +53,10 @@ static inline int stack_check_collision()
 	return ret;
 }
 
+/**
+ * @brief Get the current stack pointer value
+ * @return
+ */
 static inline uint32_t read_stack_pointer()
 {
 	uint32_t stack_pointer;