From 73606bf7a0a3967a78c54ae231bbe40b904f809e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mario=20H=C3=BCttel?= Date: Sat, 23 Oct 2021 20:54:37 +0200 Subject: [PATCH] Write documentation for the config parser --- stm-firmware/config-parser/config-parser.c | 17 +++- .../include/config-parser/config-parser.h | 84 +++++++++++++++---- 2 files changed, 82 insertions(+), 19 deletions(-) diff --git a/stm-firmware/config-parser/config-parser.c b/stm-firmware/config-parser/config-parser.c index 42635a4..291cd30 100644 --- a/stm-firmware/config-parser/config-parser.c +++ b/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,9 +62,18 @@ 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"; -static int parse_value(struct config_parser_entry *entry, char *value_start_token) +/** + * @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; char *endptr; diff --git a/stm-firmware/config-parser/include/config-parser/config-parser.h b/stm-firmware/config-parser/include/config-parser/config-parser.h index 50767ca..80d718a 100644 --- a/stm-firmware/config-parser/include/config-parser/config-parser.h +++ b/stm-firmware/config-parser/include/config-parser/config-parser.h @@ -33,44 +33,68 @@ #include #include +/** + * @brief Confi parser instance struct + */ struct config_parser { - uint32_t magic; - bool write; - FIL file; - char *buffer; - size_t buff_size; + uint32_t magic; /**< @brief Magic value. Checked by each function to verify if the passed pointer is valid */ + bool write; /**< @brief File opened in write / read mode */ + FIL file; /**< @brief FatFS file */ + char *buffer; /**< @brief Working buffer */ + 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_PARAM_ERR, - CONFIG_PARSER_GENERIC_ERR, - CONFIG_PARSER_IOERR, - CONFIG_PARSER_LINE_COMMENT, - CONFIG_PARSER_LINE_TOO_LONG, - CONFIG_PARSER_LINE_MALFORM, - CONFIG_PARSER_END_REACHED, - CONFIG_PARSER_WRONG_MODE, + CONFIG_PARSER_OK = 0, /**< @brief Operation succeeded */ + CONFIG_PARSER_PARAM_ERR, /**< @brief Function parameter error */ + CONFIG_PARSER_GENERIC_ERR, /**< @brief Generic unspecified error */ + CONFIG_PARSER_IOERR, /**< @brief I/O Error while file handling */ + CONFIG_PARSER_LINE_COMMENT, /**< @brief The parser encountered a line starting with a comment. */ + CONFIG_PARSER_LINE_TOO_LONG, /**< @brief The read line is too long for the parser to process. */ + CONFIG_PARSER_LINE_MALFORM, /**< @brief Malfoirmed line. Line is neither a commenbt nor a key=value string */ + CONFIG_PARSER_END_REACHED, /**< @brief The config parser has reached the end of the file */ + 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; - enum config_parser_value_type type; + const char *name; /**< @brief Pointer to the name of the config entry (key) */ + 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_ */