Done TODO: Comment coverage > lib > base.h

Pretty simple

lib/base.h

@@ -15,6 +15,7 @@
 
 #include <stdint.h>
 
+/* Basic macros for a variety of uses.  Quite self explanatory. */
 #define ARR_SIZE(xs) (sizeof(xs) / sizeof(xs[0]))
 #define MAX(a, b)    ((a) > (b) ? (a) : (b))
 #define MIN(a, b)    ((a) > (b) ? (b) : (a))
@@ -23,7 +24,7 @@
 #define TERM_RED     "\e[0;31m"
 #define TERM_RESET   "\e[0;0m"
 
-// Flags
+// Flags for program behaviour (usually related to printing)
 #ifndef VERBOSE
 #define VERBOSE 0
 #endif
@@ -31,6 +32,7 @@
 #define PRINT_HEX 0
 #endif
 
+/* Ease of use aliases for numeric types */
 typedef uint8_t u8;
 typedef int8_t i8;
 typedef uint32_t u32;
@@ -48,6 +50,14 @@ typedef i32 s_hword;
 typedef u64 word;
 typedef i64 s_word;
 
+/* Macros for the sizes of common base data types. */
+#define HWORD_SIZE  sizeof(hword)
+#define SHWORD_SIZE sizeof(s_hword)
+#define WORD_SIZE   sizeof(word)
+#define SWORD_SIZE  sizeof(s_word)
+
+/** Union for all basic data types in the virtual machine.
+ */
 typedef union
 {
   byte as_byte;
@@ -58,6 +68,8 @@ typedef union
   s_word as_long;
 } data_t;
 
+/** Enum of type tags for the data_t structure to provide context.
+ */
 typedef enum
 {
   DATA_TYPE_NIL = 0,
@@ -66,25 +78,54 @@ typedef enum
   DATA_TYPE_WORD,
 } data_type_t;
 
-#define DBYTE(BYTE)           ((data_t){.as_byte = (BYTE)})
-#define DHWORD(HWORD)         ((data_t){.as_hword = (HWORD)})
-#define DWORD(WORD)           ((data_t){.as_word = (WORD)})
+/* Some macros for constructing data_t instances quickly. */
+#define DBYTE(BYTE)   ((data_t){.as_byte = (BYTE)})
+#define DHWORD(HWORD) ((data_t){.as_hword = (HWORD)})
+#define DWORD(WORD)   ((data_t){.as_word = (WORD)})
+
+/** Safely subtract SUB from W, where both are words (64 bit integers).
+ *
+ * In case of underflow (i.e. where W - SUB < 0) returns 0 instead of
+ * the underflowed result.
+ */
 #define WORD_SAFE_SUB(W, SUB) ((W) > (SUB) ? ((W) - (SUB)) : 0)
 
-#define HWORD_SIZE  sizeof(hword)
-#define SHWORD_SIZE sizeof(s_hword)
-#define WORD_SIZE   sizeof(word)
-#define SWORD_SIZE  sizeof(s_word)
+/** Return the Nth byte of WORD
+ * N should range from 0 to 7 as there are 8 bytes in a word.
+ */
+#define WORD_NTH_BYTE(WORD, N) (((WORD) >> ((N) * 8)) & 0xFF)
 
-// Macros to extract the nth byte or nth hword from a word
-#define WORD_NTH_BYTE(WORD, N)  (((WORD) >> ((N)*8)) & 0xFF)
-#define WORD_NTH_HWORD(WORD, N) (((WORD) >> ((N)*2)) & 0xFFFFFFFF)
+/** Return the Nth half word of WORD
+ * N should range from 0 to 1 as there are 2 half words in a word
+ */
+#define WORD_NTH_HWORD(WORD, N) (((WORD) >> ((N) * 2)) & 0xFFFFFFFF)
 
-// Assume array contains 4 bytes.
-hword convert_bytes_to_hword(byte *);
-void convert_hword_to_bytes(hword, byte *);
-// Assume array contains 8 bytes.
+/** Convert a buffer of bytes to a half word
+ * We assume the buffer of bytes are in virtual machine byte code
+ * format (big endian) and that they are at least HWORD_SIZE in
+ * size.
+ */
+hword convert_bytes_to_hword(byte *buffer);
+
+/** Convert a half word into a VM byte code format bytes (big endian)
+ * @param h: Half word to convert
+ * @param buffer: Buffer to store into.  We assume the buffer has at
+ * least HWORD_SIZE space.
+ */
+void convert_hword_to_bytes(hword h, byte *buffer);
+
+/** Convert a buffer of bytes to a word
+ * We assume the buffer of bytes are in virtual machine byte code
+ * format (big endian) and that they are at least WORD_SIZE in
+ * size.
+ */
 word convert_bytes_to_word(byte *);
-void convert_word_to_bytes(word, byte *);
+
+/** Convert a word into a VM byte code format bytes (big endian)
+ * @param w: Word to convert
+ * @param buffer: Buffer to store into.  We assume the buffer has at
+ * least WORD_SIZE space.
+ */
+void convert_word_to_bytes(word w, byte *buffer);
 
 #endif

todo.org

@@ -4,8 +4,8 @@
 
 * TODO Better documentation [0%] :DOC:
 ** TODO Comment coverage [0%]
-*** WIP Lib [0%]
-**** WIP lib/base.h
+*** WIP Lib [25%]
+**** DONE lib/base.h
 **** TODO lib/darr.h
 **** TODO lib/heap.h
 **** TODO lib/inst.h