From cd15c4197bde211b72a50b7dd7fae4decd503224 Mon Sep 17 00:00:00 2001 From: Thomas Bernard Date: Thu, 15 Nov 2018 23:24:32 +0100 Subject: [PATCH] Doxygen for saveini/readini --- src/readini.c | 76 +++++++++++++++++++++++++++++++++++++++++++-------- src/readini.h | 2 +- src/saveini.c | 59 ++++++++++++++++++++++++++++++--------- src/saveini.h | 2 +- 4 files changed, 113 insertions(+), 26 deletions(-) diff --git a/src/readini.c b/src/readini.c index b41aa2e9..edf4e9fe 100644 --- a/src/readini.c +++ b/src/readini.c @@ -43,7 +43,18 @@ #include "io.h" #include "windows.h" - +/** + * Clean a line of the ini file. + * + * - Suppress all leading and trailing spaces + * - convert the key to uppercase + * + * Comments start with ";". The result will be in the following format : + * KEY=value + * + * @param[in,out] str + * @param[in] keep_comments if set, the comments are kept + */ void Load_INI_clear_string(char * str, byte keep_comments) { int index; @@ -94,9 +105,15 @@ void Load_INI_clear_string(char * str, byte keep_comments) } } - - -int Load_INI_seek_pattern(char * buffer,char * pattern) +/** + * Search for a substring in a string + * + * @param buffer the string to search into + * @param pattern the string to search for + * @return 0 if the pattern was not found + * @return >0 the position (+1) where the pattern was found + */ +int Load_INI_seek_pattern(const char * buffer,const char * pattern) { int buffer_index; int pattern_index; @@ -120,9 +137,13 @@ int Load_INI_seek_pattern(char * buffer,char * pattern) return 0; } - - -int Load_INI_reach_group(FILE * file,char * buffer,char * group) +/** + * Read lines until a group is found + * + * @return 0 when the group is reached + * @return @ref ERROR_INI_CORRUPTED if the group is not found + */ +static int Load_INI_reach_group(FILE * file,char * buffer,const char * group) { int stop_seek; char * group_upper; @@ -171,7 +192,9 @@ int Load_INI_reach_group(FILE * file,char * buffer,char * group) /// @param option_name string to search /// @param return_code the found value will be copied there. (must be allocaed) /// @param raw_text Boolean: true to return the raw value (up to end-of-line), false to strip comments. -int Load_INI_get_string(FILE * file,char * buffer,char * option_name,char * return_code, byte raw_text) +/// @return 0 when OK +/// @return @ref ERROR_INI_CORRUPTED if the option is not found +static int Load_INI_get_string(FILE * file,char * buffer,const char * option_name,char * return_code, byte raw_text) { int stop_seek; char * option_upper; @@ -223,7 +246,19 @@ int Load_INI_get_string(FILE * file,char * buffer,char * option_name,char * retu return 0; } -int Load_INI_get_value(char * str,int * index,int * value) +/** + * Read a value from the string + * + * @ref index is updated according to the number of characters read + * from the source string. + * + * @param str the source string (option "values") + * @param index a pointer to the current index in the source string + * @param value the read value will be put there + * @return 0 + * @return @ref ERROR_INI_CORRUPTED + */ +static int Load_INI_get_value(const char * str,int * index,int * value) { int negative = 0; @@ -349,8 +384,20 @@ int Load_INI_get_value(char * str,int * index,int * value) } - -int Load_INI_get_values(FILE * file,char * buffer,char * option_name,int nb_expected_values,int * values) +/** + * Read all values from a string + * + * The values are comma separated + * + * @param file handle to gfx2.ini + * @param buffer Current text buffer, preserved from one call to the next + * @param option_name name of the option to read + * @param nb_expected_values number of values to read from the line + * @param[out] values the values will be put there + * @return 0 when OK + * @return @ref ERROR_INI_CORRUPTED if no value was found, or not enough + */ +static int Load_INI_get_values(FILE * file,char * buffer,const char * option_name,int nb_expected_values,int * values) { int stop_seek; char * option_upper; @@ -432,6 +479,13 @@ int Load_INI_get_values(FILE * file,char * buffer,char * option_name,int nb_expe } +/** + * Load config from the gfx2.ini file + * + * @param[out] conf the configuration to read to + * @return 0 when OK + * @return @ref ERROR_INI_CORRUPTED for any error + */ int Load_INI(T_Config * conf) { FILE * file; diff --git a/src/readini.h b/src/readini.h index e55152f3..5bc2b5b9 100644 --- a/src/readini.h +++ b/src/readini.h @@ -25,5 +25,5 @@ ////////////////////////////////////////////////////////////////////////////// int Load_INI(T_Config * conf); -int Load_INI_seek_pattern(char * buffer,char * pattern); +int Load_INI_seek_pattern(const char * buffer, const char * pattern); void Load_INI_clear_string(char * str, byte keep_comments); diff --git a/src/saveini.c b/src/saveini.c index 72114ebf..ad7b8c43 100644 --- a/src/saveini.c +++ b/src/saveini.c @@ -34,7 +34,10 @@ #include "setup.h" #include "windows.h" -int Save_INI_reach_group(FILE * old_file,FILE * new_file,char * buffer,char * group) +/** + * go forward in gfx2.ini until the group is found + */ +static int Save_INI_reach_group(FILE * old_file,FILE * new_file,char * buffer,const char * group) { int stop_seek; char * group_upper; @@ -81,8 +84,14 @@ int Save_INI_reach_group(FILE * old_file,FILE * new_file,char * buffer,char * gr } - -int Save_INI_char_in_value_alphabet(char c) +/** + * Check if a character is [-$.0-9A-Z] + * which are the allowed characters for values + * + * @return 1 for a matching character + * @return 0 for any other character + */ +static int Save_INI_char_in_value_alphabet(char c) { if ( ( // Digit @@ -107,8 +116,16 @@ int Save_INI_char_in_value_alphabet(char c) } - -void Save_INI_set_value(char * dest,char * source,int nb_values_to_set,int * values,int litteral) +/** + * build a gfx2.ini line + * + * @param[out] dest the destination buffer + * @param source the original gfx2.ini line + * @param nb_values_to_set the number of values to set + * @param values the array of values + * @param litteral if true, the value name is written, else the digital value + */ +static void Save_INI_set_value(char * dest,const char * source,int nb_values_to_set,const int * values,int litteral) { int dest_index; int source_index; @@ -202,7 +219,14 @@ void Save_INI_set_value(char * dest,char * source,int nb_values_to_set,int * val } } -void Save_INI_set_string(char * dest,char * source,char * value) +/** + * build a gfx2.ini line + * + * @param[out] dest receiving buffer for the line + * @param source original gfx2.ini line + * @param value value to write + */ +static void Save_INI_set_string(char * dest,const char * source,const char * value) { int dest_index; int source_index; @@ -237,7 +261,10 @@ void Save_INI_set_string(char * dest,char * source,char * value) dest[dest_index]='\0'; } -int Save_INI_set_strings(FILE * old_file,FILE * new_file,char * buffer,char * option_name,char * value) +/** + * Set an option value in gfx2.ini + */ +static int Save_INI_set_strings(FILE * old_file,FILE * new_file,char * buffer,const char * option_name,const char * value) { int stop_seek; char * option_upper; @@ -312,7 +339,10 @@ int Save_INI_set_strings(FILE * old_file,FILE * new_file,char * buffer,char * op return 0; } -int Save_INI_set_values(FILE * old_file,FILE * new_file,char * buffer,char * option_name,int nb_values_to_set,int * values,int litteral) +/** + * set option values in the gfx2.ini file + */ +static int Save_INI_set_values(FILE * old_file,FILE * new_file,char * buffer,const char * option_name,int nb_values_to_set,const int * values,int litteral) { int stop_seek; char * option_upper; @@ -384,17 +414,20 @@ int Save_INI_set_values(FILE * old_file,FILE * new_file,char * buffer,char * opt return 0; } - - -void Save_INI_flush(FILE * old_file,FILE * new_file,char * buffer) +/** + * copy all remaining lines + */ +static void Save_INI_flush(FILE * old_file,FILE * new_file,char * buffer) { while (fgets(buffer,1024,old_file)!=0) fprintf(new_file,"%s",buffer); } - -int Save_INI(T_Config * conf) +/** + * Save the config to the gfx2.ini file + */ +int Save_INI(const T_Config * conf) { FILE * old_file; FILE * new_file; diff --git a/src/saveini.h b/src/saveini.h index c45b38f5..45005242 100644 --- a/src/saveini.h +++ b/src/saveini.h @@ -24,4 +24,4 @@ /// Saving settings in gfx2.ini ////////////////////////////////////////////////////////////////////////////// -int Save_INI(T_Config * conf); +int Save_INI(const T_Config * conf);