Doxygen for saveini/readini

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 :
+ * <tt>KEY=value</tt>
+ *
+ * @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)
   }
 }
 
-
+/**
-
+ * Search for a substring in a string
-int Load_INI_seek_pattern(char * buffer,char * pattern)
+ *
+ * @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;
 }
 
-
+/**
-
+ * Read lines until a group is found
-int Load_INI_reach_group(FILE * file,char * buffer,char * group)
+ *
+ * @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;

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);

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;
 }
 
-
+/**
-
+ * copy all remaining lines
-void Save_INI_flush(FILE * old_file,FILE * new_file,char * buffer)
+ */
+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;

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);