Write documentation for the config parser

stm-firmware/config-parser/config-parser.c

@@ -31,6 +31,12 @@
 #define CONFIG_PARSER_MAGIC 0x464a6e2bUL
 #define CONFIG_PARSER(p) ((struct config_parser *)(p))
 
+/**
+ * @brief Check if the supplied pointer is a valid @ref config_parser_handle_t
+ *
+ * If the pointer is invalid, the function using this macro will return with
+ * CONFIG_PARSER_PARAM_ERR
+ */
 #define config_parser_check_handle(handle) do { if (!(handle) || \
 						((struct config_parser *)(handle))->magic != CONFIG_PARSER_MAGIC) \
 							return CONFIG_PARSER_PARAM_ERR; \
@@ -56,8 +62,17 @@ config_parser_handle_t config_parser_open_file(struct config_parser *config_pars
 	return (config_parser_handle_t)config_parser;
 }
 
+/**
+ * @brief Token delimiters for the config parser.
+ */
 static const char * const token_delim = " \t";
 
+/**
+ * @brief Parse a value in the configuration
+ * @param entry Entry to parse the value in to
+ * @param value_start_token char pointer holding the value. Must be null-terminated
+ * @return 0 if successful
+ */
 static int parse_value(struct config_parser_entry *entry, char *value_start_token)
 {
 	char *dot;

stm-firmware/config-parser/include/config-parser/config-parser.h

@@ -33,44 +33,68 @@
 #include <stdbool.h>
 #include <fatfs/ff.h>
 
+/**
+ * @brief Confi parser instance struct
+ */
 struct config_parser {
-	uint32_t magic;
+	uint32_t magic; /**< @brief Magic value. Checked by each function to verify if the passed pointer is valid */
-	bool write;
+	bool write; /**< @brief File opened in write / read mode */
-	FIL file;
+	FIL file; /**< @brief FatFS file */
-	char *buffer;
+	char *buffer; /**< @brief Working buffer */
-	size_t buff_size;
+	size_t buff_size; /** @brief Size of the working buffer config_parser::buffer */
 };
 
+/**
+ * @brief handle type for the config parser. Never dereference this pointer directly!
+ */
 typedef void * config_parser_handle_t;
 
+/**
+ * @brief Differnet value types a config entry can hold
+ */
 enum config_parser_value_type {
 	CONFIG_PARSER_TYPE_UINT = 0,
 	CONFIG_PARSER_TYPE_INT,
 	CONFIG_PARSER_TYPE_FLOAT,
 };
 
+/**
+ * @brief Error return code of config parser functions
+ */
 enum config_parser_ret {
-	CONFIG_PARSER_OK = 0,
+	CONFIG_PARSER_OK = 0, /**< @brief Operation succeeded */
-	CONFIG_PARSER_PARAM_ERR,
+	CONFIG_PARSER_PARAM_ERR, /**< @brief Function parameter error */
-	CONFIG_PARSER_GENERIC_ERR,
+	CONFIG_PARSER_GENERIC_ERR, /**< @brief Generic unspecified error */
-	CONFIG_PARSER_IOERR,
+	CONFIG_PARSER_IOERR, /**< @brief I/O Error while file handling */
-	CONFIG_PARSER_LINE_COMMENT,
+	CONFIG_PARSER_LINE_COMMENT, /**< @brief The parser encountered a line starting with a comment. */
-	CONFIG_PARSER_LINE_TOO_LONG,
+	CONFIG_PARSER_LINE_TOO_LONG, /**< @brief The read line is too long for the parser to process. */
-	CONFIG_PARSER_LINE_MALFORM,
+	CONFIG_PARSER_LINE_MALFORM, /**< @brief Malfoirmed line. Line is neither a commenbt nor a key=value string */
-	CONFIG_PARSER_END_REACHED,
+	CONFIG_PARSER_END_REACHED, /**< @brief The config parser has reached the end of the file */
-	CONFIG_PARSER_WRONG_MODE,
+	CONFIG_PARSER_WRONG_MODE, /**< @brief Read or write requested on config parser instance that is opened in a different mode */
 };
 
+/**
+ * @brief Represents a configuration key-value-pair used by the config parser
+ */
 struct config_parser_entry {
-	const char *name;
+	const char *name; /**< @brief Pointer to the name of the config entry (key) */
-	enum config_parser_value_type type;
+	enum config_parser_value_type type; /**< @brief Type of the value held by this struct */
 	union {
 		uint32_t uint_val;
 		int32_t int_val;
 		float float_val;
-	} value;
+	} value; /**< @brief Value of the config entry. For correct processing, config_parser_entry::type has to be taken into account */
 };
 
+/**
+ * @brief Open a config file
+ * @param config_parser Struict holding the config parser isntance. Will be filled by this function
+ * @param write Open the config file for writing (true) or reading (false)
+ * @param file_name File name to open
+ * @param working_buffer A working buffer used by the config parser to process the file.
+ * @param buff_size Size of \p working_buffer. Must be large enough to hold a full line of the config file
+ * @return Config parser error
+ */
 config_parser_handle_t config_parser_open_file(struct config_parser *config_parser, bool write, const char *file_name,
 					       char *working_buffer, size_t buff_size);
 
@@ -83,13 +107,37 @@ config_parser_handle_t config_parser_open_file(struct config_parser *config_pars
  * @return Config parser error
  */
 enum config_parser_ret config_parser_get_line(config_parser_handle_t handle, struct config_parser_entry *entry, bool force_float);
-
+/**
+ * @brief Reset the config parser instance to the beginning of the config file
+ * @param handle Config parser
+ * @return Config parser error
+ */
 enum config_parser_ret config_parser_reset_to_start(config_parser_handle_t handle);
 
+/**
+ * @brief Write a config entry to a config file
+ * @param handle Handle to the config parser. This must be opened in write mode.
+ * @param entry
+ * @return Config parser error
+ * @warning This function is currently not implemented and will return with a success!
+ */
 enum config_parser_ret config_parser_write_entry(config_parser_handle_t handle, const struct config_parser_entry *entry);
 
+/**
+ * @brief Close a config parser handle
+ * @param handle Config parser
+ * @return Config parser error
+ */
 enum config_parser_ret config_parser_close_file(config_parser_handle_t handle);
 
+/**
+ * @brief Check if the \p return_val is a abort condition to stop parsing a file.
+ *
+ * This function will return true if a disk error occured or the end of file is reached.
+ *
+ * @param return_val
+ * @return
+ */
 bool config_parser_ret_is_abort_condition(enum config_parser_ret return_val);
 
 #endif /* _CONFIG_PARSER_H_ */