better comments and legibility

* add better comments to the code structure
 * on decrement_number_string(), renamed arguments for better legibility

Signed-off-by: Daniel Santos <dacs.git@brilhante.top>

numericx.c

@@ -6,10 +6,21 @@
 
 #define PROG_NAME "numericx"
 
+
+/* ||COMPILATION FLAGS|| */
+
+/*
+ * Show debug message of step by step
+ * incrementation of the number
+ */
 #ifndef DEBUG
 #define DEBUG false
 #endif
 
+/*
+ * Configuration of the corresponding numeral system
+ * to have the units place of the end (on the right)
+ */
 #ifndef TO_UNITS_ON_THE_END
 #define TO_UNITS_ON_THE_END false
 #endif
@@ -18,6 +29,11 @@
 #define FROM_UNITS_ON_THE_END false
 #endif
 
+/*
+ * Configuration of the corresponding numeral system
+ * to start counting on the second number, being the
+ * first number void
+ */
 #ifndef TO_FIRST_NUMBER_VOID
 #define TO_FIRST_NUMBER_VOID false
 #endif
@@ -26,6 +42,11 @@
 #define FROM_FIRST_NUMBER_VOID false
 #endif
 
+/* Configuration of the corresponding numeral system
+ * to have the first number as an infinite number,
+ * for example, if the first number is 'A', then
+ * A == AA == AAA == AAAA ...
+ */
 #ifndef TO_INFINITE_BASE
 #define TO_INFINITE_BASE false
 #endif
@@ -34,6 +55,9 @@
 #define FROM_INFINITE_BASE false
 #endif
 
+
+/* ||DATA STRUCTURE|| */
+
 typedef struct NumeralPtr
 {
 	char const* symbol;
@@ -41,10 +65,17 @@ typedef struct NumeralPtr
 	struct NumeralPtr *previous;
 } numeral_ptr;
 
+
+/* ||FUNCTIONS|| */
+
 /*
- * Creates new digit for numeral_ptr
+ * Creates new digit for numeral_ptr.
- * Return pointer to new numeral_ptr
+ * It needs the last_numeral ('last_numeral') into which will
- * Returns NULL in case of no memory
+ * add the new numeral, and also need to know the symbol of the
+ * new numeral ('to_first').
+ *
+ * Return pointer to new numeral_ptr.
+ * Returns NULL in case of no memory.
  */
 numeral_ptr*
 new_digit(numeral_ptr* last_numeral, char const* to_first)
@@ -63,6 +94,15 @@ new_digit(numeral_ptr* last_numeral, char const* to_first)
 	return starting_point;
 }
 
+/*
+ * Creates a number of the form numeral_ptr that
+ * begins with 'case' number of cases, and all cases
+ * are set to 'to_first' char.
+ *
+ * Returns pointer to numeral_ptr.
+ * Returns NULL in case of no memory (because depends
+ * on new_digit() ).
+ */
 numeral_ptr*
 numeral_infinity(char const* to_first, size_t cases)
 {
@@ -78,6 +118,13 @@ numeral_infinity(char const* to_first, size_t cases)
 	return starting_case;
 }
 
+/* Increments numeral_ptr 'numeral' one unit up.
+ * It needs 'num_first' as the first numeral of the numerical
+ * system. Also needs 'num_last' as the last numeral of the
+ * numerical system.
+ * If incrementing, the function adds a new digit/numeral, it
+ * will use the 'brand_new_digit' as its numeral/digit.
+ */
 void
 increment(numeral_ptr* numeral, char* num_first, char* num_last, char* brand_new_digit)
 {
@@ -99,12 +146,19 @@ increment(numeral_ptr* numeral, char* num_first, char* num_last, char* brand_new
 		++(numeral->symbol);
 }
 
+/*
+ * Decrements a string 'number' by one unit.
+ * It needs to know the first numeral ('first_numeral') and also the
+ * last numeral ('last_numeral'). It also needs the numeral system in
+ * form of a string ('numeral_system') to know which is the numeral
+ * before the actual numeral that needs decrementation.
+ */
 void
-decrement_number_string(char* number, char* first_number, char* last_number, char* numeral_system)
+decrement_number_string(char* number, char* first_numeral, char* last_numeral, char* numeral_system)
 {
-	while( *number == *first_number )
+	while( *number == *first_numeral )
 	{
-		*number = *last_number;
+		*number = *last_numeral;
 		++number;
 	}
 
@@ -121,6 +175,11 @@ decrement_number_string(char* number, char* first_number, char* last_number, cha
 	}
 }
 
+/*
+ * Compares if a numeral_ptr ('numeral') matches the string ('number_arg').
+ *
+ * Return true if matches, false if numeral_ptr doesn't match the string.
+ */
 bool
 is_the_same(numeral_ptr* numeral, char* number_arg)
 {
@@ -139,6 +198,9 @@ is_the_same(numeral_ptr* numeral, char* number_arg)
 	return (*number_arg == '\0') ? true : false;
 }
 
+/*
+ * Prints to standard output numeral_ptr ('numeral').
+ */
 void
 print_numeral(numeral_ptr* numeral)
 {
@@ -163,6 +225,9 @@ print_numeral(numeral_ptr* numeral)
 	}
 }
 
+/*
+ * Reverse a string.
+ */
 void
 reverse_string(char* string)
 {
@@ -177,6 +242,14 @@ reverse_string(char* string)
 	}
 }
 
+/*
+ * Check if string 'number' belongs to the numerical
+ * system ('numeral_system'), which is also a string.
+ * Belonging mean all the symbols of 'number' are included
+ * in 'numeral_system'.
+ *
+ * Return true if it belongs, false otherwise.
+ */
 bool
 is_valid_number(char* numeral_system, char *number)
 {
@@ -194,6 +267,9 @@ is_valid_number(char* numeral_system, char *number)
 	return true;
 }
 
+/*
+ * Free up numeral_ptr ('numeral').
+ */
 void
 free_numeral(numeral_ptr* numeral)
 {
@@ -207,6 +283,9 @@ free_numeral(numeral_ptr* numeral)
 	}
 }
 
+
+/* ||MAIN FUNCTION|| */
+
 int
 main(int argc, char* argv[])
 {