Do a lot of doc work and refactor along the way

Yay! I finished commenting the code!

Signed-off-by: Gavin Howard <gavin@yzena.com>

6 files changed, 54 insertions, 37 deletions

diff --git a/include/args.h b/include/args.h
index 6db7ff5e..a2f5b416 100644
--- a/include/args.h
+++ b/include/args.h
@@ -44,8 +44,8 @@
  * Processes command-line arguments.
  * @param argc        How many arguments there are.
  * @param argv        The array of arguments.
- * @param exit_exprs  True if bc/dc should exit there are expressions, false
- *                    otherwise.
+ * @param exit_exprs  True if bc/dc should exit when there are expressions,
+ *                    false otherwise.
  */
 void bc_args(int argc, char *argv[], bool exit_exprs);
 
diff --git a/include/bc.h b/include/bc.h
index fb70ad24..6ebb0aee 100644
--- a/include/bc.h
+++ b/include/bc.h
@@ -375,47 +375,51 @@ void bc_parse_expr(BcParse *p, uint8_t flags);
  */
 void bc_parse_parse(BcParse *p);
 
-// References to the signal message and its length.
+/// References to the signal message and its length.
 extern const char bc_sig_msg[];
 extern const uchar bc_sig_msg_len;
 
-// An array of bits that are set if the corresponding lex token is valid in an
-// expression.
+/// A reference to an array of bits that are set if the corresponding lex token
+/// is valid in an expression.
 extern const uint8_t bc_parse_exprs[];
 
-// An array of bc operators.
+/// A reference to an array of bc operators.
 extern const uchar bc_parse_ops[];
 
 // References to the various instances of BcParseNext's.
 
-// What tokens are valid as next tokens when parsing normal expressions. More
-// accurately. these are the tokens that are valid for *ending* the expression.
+/// A reference to what tokens are valid as next tokens when parsing normal
+/// expressions. More accurately. these are the tokens that are valid for
+/// *ending* the expression.
 extern const BcParseNext bc_parse_next_expr;
 
-// What tokens are valid as next tokens when parsing function parameters (well,
-// actually arguments).
-extern const BcParseNext bc_parse_next_param;
+/// A reference to what tokens are valid as next tokens when parsing function
+/// parameters (well, actually arguments).
+extern const BcParseNext bc_parse_next_arg;
 
-// What tokens are valid as next tokens when parsing a print statement.
+/// A reference to what tokens are valid as next tokens when parsing a print
+/// statement.
 extern const BcParseNext bc_parse_next_print;
 
-// What tokens are valid as next tokens when parsing things like loop headers
-// and builtin functions where the only thing expected is a right paren.
-//
-// The name is an artifact of history, and is related to @a BC_PARSE_REL (see
-// include/parse.h). It refers to how POSIX only allows some operators as part
-// of the conditional of for loops, while loops, and if statements.
+/// A reference to what tokens are valid as next tokens when parsing things like
+/// loop headers and builtin functions where the only thing expected is a right
+/// paren.
+///
+/// The name is an artifact of history, and is related to @a BC_PARSE_REL (see
+/// include/parse.h). It refers to how POSIX only allows some operators as part
+/// of the conditional of for loops, while loops, and if statements.
 extern const BcParseNext bc_parse_next_rel;
 
 // What tokens are valid as next tokens when parsing an array element
 // expression.
 extern const BcParseNext bc_parse_next_elem;
 
-// What tokens are valid as next tokens when parsing the first two parts of a
-// for loop header.
+/// A reference to what tokens are valid as next tokens when parsing the first
+/// two parts of a for loop header.
 extern const BcParseNext bc_parse_next_for;
 
-// What tokens are valid as next tokens when parsing a read expression.
+/// A reference to what tokens are valid as next tokens when parsing a read
+/// expression.
 extern const BcParseNext bc_parse_next_read;
 
 #else // BC_ENABLED
diff --git a/include/lex.h b/include/lex.h
index 724303d6..7d947f23 100644
--- a/include/lex.h
+++ b/include/lex.h
@@ -71,11 +71,14 @@
 
 #endif // BC_ENABLED
 
-/// Returns true if c is a valid number character.
-/// @param c      The char to check.
-/// @param pt     If a decimal point has already been seen.
-/// @param int_only  True if the number is expected to be an int only, false if
-///                  non-integers are allowed.
+/**
+ * Returns true if c is a valid number character.
+ * @param c         The char to check.
+ * @param pt        If a decimal point has already been seen.
+ * @param int_only  True if the number is expected to be an int only, false if
+ *                  non-integers are allowed.
+ * @return          True if @a c is a valid number character.
+ */
 #define BC_LEX_NUM_CHAR(c, pt, int_only)                               \
 	(isdigit(c) != 0 || ((c) >= 'A' && (c) <= BC_LEX_LAST_NUM_CHAR) || \
 	 ((c) == '.' && !(pt) && !(int_only)))
diff --git a/include/library.h b/include/library.h
index 520578db..8a055eb8 100644
--- a/include/library.h
+++ b/include/library.h
@@ -171,8 +171,8 @@
 
 /**
  * A header to check the number in the context and return an error encoded as a
- * number if it is bad.
  * @param c  The context.
+ * number if it is bad.
  * @param n  The BclNumber.
  */
 #define BC_CHECK_NUM(c, n)                                         \
diff --git a/include/rand.h b/include/rand.h
index 62c4f0ed..a916d0de 100644
--- a/include/rand.h
+++ b/include/rand.h
@@ -52,6 +52,16 @@
 
 #if BC_ENABLE_RAND
 
+#if BC_ENABLE_LIBRARY
+#define BC_RAND_USE_FREE (1)
+#else // BC_ENABLE_LIBRARY
+#ifndef NDEBUG
+#define BC_RAND_USE_FREE (1)
+#else // NDEBUG
+#define BC_RAND_USE_FREE (0)
+#endif // NDEBUG
+#endif // BC_ENABLE_LIBRARY
+
 /**
  * A function to return a random unsigned long.
  * @param ptr  A void ptr to some data that will help generate the random ulong.
@@ -436,7 +446,7 @@ typedef struct BcRNG {
  */
 void bc_rand_init(BcRNG *r);
 
-#ifndef NDEBUG
+#if BC_RAND_USE_FREE
 
 /**
  * Frees a BcRNG. This is only in debug builds because it would only be freed on
@@ -445,7 +455,7 @@ void bc_rand_init(BcRNG *r);
  */
 void bc_rand_free(BcRNG *r);
 
-#endif // NDEBUG
+#endif // BC_RAND_USE_FREE
 
 /**
  * Returns a random integer from the PRNG.
diff --git a/include/vm.h b/include/vm.h
index 9eb8813c..d5132fac 100644
--- a/include/vm.h
+++ b/include/vm.h
@@ -545,17 +545,11 @@ typedef struct BcVm {
 	/// A BcNum set to constant 0.
 	BcNum zero;
 
+#endif // !BC_ENABLE_LIBRARY
+
 	/// A BcNum set to constant 1.
 	BcNum one;
 
-	// The BcDig array for the zero BcNum.
-	BcDig zero_num[BC_VM_ONE_CAP];
-
-	// The BcDig array for the one BcNum.
-	BcDig one_num[BC_VM_ONE_CAP];
-
-#endif // !BC_ENABLE_LIBRARY
-
 	/// A BcNum holding the max number held by a BcBigDig plus 1.
 	BcNum max;
 
@@ -568,8 +562,14 @@ typedef struct BcVm {
 	/// The BcDig array for max2.
 	BcDig max2_num[BC_NUM_BIGDIG_LOG10];
 
+	// The BcDig array for the one BcNum.
+	BcDig one_num[BC_VM_ONE_CAP];
+
 #if !BC_ENABLE_LIBRARY
 
+	// The BcDig array for the zero BcNum.
+	BcDig zero_num[BC_VM_ONE_CAP];
+
 	/// The stdout file.
 	BcFile fout;