More documentation

include/vm_bits.h

@@ -3,6 +3,11 @@
 
 #include <stdlib.h>
 
+/*
+ * We use the 8bit and 16bit types everywhere within the "vm"
+ * abstraction; they are also used where applicable within the other
+ * systems, like the mos6502 cpu, within the apple2 machine, etc.
+ */
 typedef uint8_t vm_8bit;
 typedef uint16_t vm_16bit;
 

include/vm_screen.h

@@ -1,7 +1,18 @@
 #ifndef _VM_SCREEN_H_
 #define _VM_SCREEN_H_
 
+/*
+ * If you just want to plot a single pixel, you can use this macro to
+ * abstract away the need to indicate the x/y dimensions (as those must
+ * necessarily be 1x1).
+ */
+#define vm_screen_draw_pixel(context, xpos, ypos) \
+    vm_screen_draw_rect(context, xpos, ypos, 1, 1)
+
 typedef struct {
+    /*
+     * These form the components of an RGBA composite color. 
+     */
     int color_red;
     int color_green;
     int color_blue;
@@ -13,7 +24,4 @@ extern void vm_screen_free_context(vm_screen_context *);
 extern vm_screen_context *vm_screen_new_context();
 extern void vm_screen_set_color(vm_screen_context *, int, int, int, int);
 
-#define vm_screen_draw_pixel(context, xpos, ypos) \
-    vm_screen_draw_rect(context, xpos, ypos, 1, 1)
-
 #endif

include/vm_segment.h

@@ -3,8 +3,22 @@
 
 #include "vm_bits.h"
 
+/*
+ * The bounds check is just some inline code to try and cut down on the
+ * cost of it.
+ */
+#define vm_segment_bounds_check(segment, index) \
+	(index == index % segment->size)
+
 typedef struct {
+    /*
+     * The size of our memory segment. This is used for bounds checking.
+     */
 	size_t size;
+
+    /*
+     * This is the actual chunk of memory we allocate.
+     */
 	vm_8bit *memory;
 } vm_segment;
 
@@ -14,7 +28,4 @@ extern void vm_segment_free(vm_segment *);
 extern vm_8bit vm_segment_get(vm_segment *, size_t);
 extern void vm_segment_set(vm_segment *, size_t, vm_8bit);
 
-#define vm_segment_bounds_check(segment, index) \
-	(index == index % segment->size)
-
 #endif