Documentation for files

src/apple2.c

@@ -1,5 +1,8 @@
 /*
  * apple2.c
+ *
+ * Here we have support for the apple2 machine. I suspect that we will
+ * need to break this file up into components in the future...
  */
 
 #include "apple2.h"

src/log.c

@@ -1,3 +1,9 @@
+/*
+ * log.c
+ *
+ * The functions here support our logging mechanism.
+ */
+
 #include <stdio.h>
 #include <stdlib.h>
 #include <stdarg.h>

src/main.c

@@ -1,3 +1,11 @@
+/*
+ * main.c
+ *
+ * Here we define the main entry point for the program; we also define a
+ * couple of functions to run when we start (init) and finish
+ * (...finish).
+ */
+
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>

src/mos6502.arith.c

@@ -1,5 +1,8 @@
 /*
- * mos6502.inst.c
+ * mos6502.arith.c
+ *
+ * We define here the logic for arithmetic instructions for the MOS 6502
+ * processor.
  */
 
 #include "mos6502.h"

src/mos6502.bits.c

@@ -1,5 +1,8 @@
 /*
  * mos6502.bits.c
+ *
+ * The code here is used to implement instructions which operate
+ * specifically on bits of values.
  */
 
 #include "mos6502.h"

src/mos6502.branch.c

@@ -1,5 +1,8 @@
 /*
  * mos6502.branch.c
+ *
+ * This is all the logic we use for branch instructions, which are used
+ * for conditional expressions.
  */
 
 #include "mos6502.h"

src/mos6502.c

@@ -1,23 +1,9 @@
 /*
- * Ideas:
+ * mos6502.c
  *
- * The mos6502 code would _just_ emulate said chip. It would not be a
- * technical part of the computer, and it would in other words be
- * decoupled from the notion of a commadore, apple ii, etc.
- *
- * What you need to do in order to emulate the chip is be able to know
- * about _memory_, and know about _registers_. Things like disk drives,
- * screens, etc. are sort of beyond its knowledge. But memory and
- * registers must be _local_ to the chip's workings; it must be able to
- * directly modify those, as well as share memory/registers/etc. with
- * other parts of a platform.
- *
- * Observations:
- *   - there can only be one chip at a given time; therefore we can get
- *   away with some kind of singleton to represent the chip
- *   - registers and memory need to be available to the chip, but the
- *   chip should not know about the larger platform; we should have
- *   pointers to all of that in the chip structure
+ * These functions are kind of the "top-level", if you will, for the MOS
+ * 6502 processor. You can create the processor struct, operate on the
+ * stack, etc.
  */
 
 #include <stdio.h>

src/mos6502.exec.c

@@ -1,5 +1,8 @@
 /*
  * mos6502.exec.c
+ *
+ * These instructions concern program execution; things like JMP, JSR,
+ * BRK, and so forth.
  */
 
 #include "mos6502.h"

src/mos6502.loadstor.c

@@ -1,5 +1,8 @@
 /*
  * mos6502.loadstor.c
+ *
+ * These are all the instructions which load and store values into
+ * various registers and places in memory.
  */
 
 #include "mos6502.h"

src/mos6502.stat.c

@@ -1,5 +1,8 @@
 /*
  * mos6502.stat.c
+ *
+ * The "stat", here, is short for status; these instructions all
+ * directly modify the status (P) register.
  */
 
 #include "mos6502.h"

src/option.c

@@ -1,5 +1,9 @@
 /*
- * options.c
+ * option.c
+ * 
+ * This file contains the functions which support our CLI options; you
+ * are both able to parse options and retrieve information from that
+ * option parsing.
  */
 
 #include <errno.h>

src/vm_screen.c

@@ -1,3 +1,11 @@
+/*
+ * vm_screen.c
+ *
+ * Functions here support drawing to the virtual machine's "screen";
+ * exactly how that is done is an abstraction to the rest of the
+ * program, which only knows to call the functions here.
+ */
+
 #include <stdlib.h>
 
 #include "log.h"

src/vm_segment.c

@@ -1,21 +1,10 @@
 /*
  * vm_segment.c
- *   memory segments for our virtual machine
  *
- * Memory segments can be used for almost any kind of storage we can
- * imagine. The most obvious use would be for system memory, but others
- * would include physical disk media (floppy disks, hard drives).
- *
- * You may note that we assume memory segments are organized into 8bit
- * values (the `vm_8bit` type). It's certainly possible to create memory
- * segments which are organized into arbitrary boundaries; 2, 3, 4
- * bytes, you know, go nuts!
- *
- * To do so, however, we would be adding a fair bit of complexity, and
- * (at the moment of this writing at least) I am not convinced there is
- * a good use-case for doing so. Your bog-standard computer of _today_
- * is still using memory organized into bytes. Your hard drive is also
- * using bytes. Etc.
+ * The functions here allow you to allocate generic blocks of memory (or
+ * "segments") for use anywhere else in the software. They can be used
+ * to represent machine memory, removable media (like floppy disks),
+ * etc.
  */
 
 #include <stdio.h>