Add block comments to describe source files

src/apple2.bank.c

@@ -1,5 +1,16 @@
 /*
  * apple2.bank.c
+ *
+ * Handle reads and writes to bank-switchable memory, as well as the
+ * soft switches that manage access to bank-switched memory spaces.
+ * Bank-switchable memory is located from $D000..$FFFF, and those
+ * addresses may point to 1) system ROM; 2) main memory RAM; 3)
+ * auxiliary memory RAM; 4) a separate 4k bank of RAM in the
+ * $D000..$DFFF range, one for _each_ of main and aux memory. That is,
+ * you are allowed to fit a separate 16k RAM in 12k address space for
+ * both main and auxiliary memory.
+ *
+ * Are you confused yet? Keep reading!
  */
 
 #include "apple2.h"

src/apple2.c

@@ -1,8 +1,9 @@
 /*
  * 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...
+ * This file handles the top-level domain code for the Apple II machine.
+ * It's also a bit of a catch-all for logic which doesn't need its own
+ * file.
  */
 
 #include <unistd.h>

src/apple2.dbuf.c

@@ -1,5 +1,11 @@
 /*
  * apple2.dbuf.c
+ *
+ * Handle reads and writes to our display buffers and the soft switches
+ * that manage them. There are a number of conditions which may cause
+ * our I/O to use the auxiliary memory segment instead of the main one;
+ * additionally, we can signal to the VM that we need to redraw stuff
+ * when writes do happen.
  */
 
 #include "apple2.dbuf.h"

src/apple2.dd.c

@@ -1,5 +1,12 @@
 /*
  * apple2.dd.c
+ *
+ * This file encompasses the logic we use to handle disk drives in the
+ * Apple II machine. You'll find a lot of references to what may seem to
+ * be hardware implementation details, like stepper motor phases, but
+ * these are necessary because those details were exposed to software,
+ * and software was required to use those details to correctly position
+ * itself.
  */
 
 #include "apple2.dd.h"

src/apple2.dec.c

@@ -1,5 +1,8 @@
 /*
  * apple2.dec.c
+ *
+ * Decode 6-and-2 encoding to get back to the "raw" state that image
+ * data has. You can read more on why this is necessary in apple2.enc.c.
  */
 
 #include <stdbool.h>

src/apple2.draw.c

@@ -1,5 +1,9 @@
 /*
  * apple2.draw.c
+ *
+ * Draw pretty pixels on the screen in the way that Apple II would work.
+ * NB: this code is pretty rough, and I expect some changes as we get
+ * further into development.
  */
 
 #include "apple2.h"

src/apple2.enc.c

@@ -1,5 +1,14 @@
 /*
  * apple2.enc.c
+ *
+ * Encode disk image data with 6-and-2 encoding, which in effect
+ * "nibbilizes" them (in exactly the way a .NIB file is saved). This
+ * process is somewhat complicated, and I don't blame you if you gently
+ * bop your head on your desk and ask woz, pleadingly, why, why, why.
+ *
+ * The reason for "why" is that early disk drives were pretty limited,
+ * and specifically could not have zero bits next to each other. Which
+ * is _crazy_. Hence the crazy code below. 
  */
 
 #include "apple2.enc.h"

src/apple2.kb.c

@@ -1,5 +1,10 @@
 /*
  * apple2.kb.c
+ *
+ * Handle soft switches to read keyboard state, which are surprisingly
+ * few and lightweight. The state would be the last key pressed, whether
+ * a key is pressed _right now_, and the keyboard strobe (which is used
+ * to determine if you've read last key pressed before or not).
  */
 
 #include "apple2.kb.h"

src/apple2.mem.c

@@ -1,5 +1,10 @@
 /*
  * apple2.mem.c
+ *
+ * Implement code to handle soft switches for memory modes in Apple II,
+ * to handle zero-page accesses, and to handle ROM initialization. If
+ * that sounds like a lot of not-necessarily-related stuff, you're
+ * right! FIXME: we should break this file up into smaller parts.
  */
 
 #include "apple2.bank.h"

src/apple2.reflect.c

@@ -1,5 +1,8 @@
 /*
  * apple2.reflect.c
+ *
+ * Implement the reflection handlers for the virtual machine when the
+ * apple2 machine is being emulated.
  */
 
 #include "apple2.h"

src/mos6502.dis.c

@@ -1,7 +1,27 @@
 /*
  * mos6502.dis.c
  *
- * Disassembly of the mos6502 machine code into an assembly notation.
+ * Disassembly of the mos6502 machine code into an assembly notation. I
+ * should note that there is no formal grammar (that I know of!) for
+ * 6502 assembly--just an informal notation that is de-facto supported
+ * by one assembler or another. The general format we use is as follows:
+ *
+ * LABEL:
+ *     INS    $OPER       ; comment
+ *
+ * Where LABEL is a--well, a label; INS is an instruction; $OPER is a
+ * hexadecimal number; and a semicolon denotes a comment follows until
+ * the end of the line.
+ *
+ * You will find a number of variants of `$OPER`, as the assembly
+ * notation uses those variants to denote a specific kind of address
+ * mode. `$OPER` is absolute mode; `$OP` (just two hex digits) is
+ * zero-page mode; `$(OP),Y` is indirect-indexed mode; etc. (Please
+ * refer to mos6502.addr.c for more details on those modes!)
+ *
+ * The code here generally pushes disassembled notation into FILE stream
+ * objects. If you need them in a string, for instance, you can mess
+ * with `setvbuf()` (as we indeed do in our unit-testing code!).
  */
 
 #include <stdbool.h>

src/objstore.c

@@ -1,5 +1,10 @@
 /*
  * objstore.c
+ *
+ * The code here allows us to work with the object store, which is an
+ * entity that allows us to toss all of our binary data needs into a big
+ * glob of stuff that we can unpack and use at runtime. Examples of such
+ * data are bitmap fonts, ROM data, etc.
  */
 
 #include <zlib.h>

src/vm_area.c

@@ -1,5 +1,12 @@
 /*
  * vm_area.c
+ *
+ * The area code defines a library-independent "area" struct, because we
+ * don't want to write virtual machine code which makes literal use of
+ * SDL_Rects. Any time you need to pass a screen area (which would be a
+ * rectangle of a certain width and height, offset from the top-left of
+ * the screen by a given x/y coordinate), you would use a vm_area
+ * struct to do so.
  */
 
 #include "vm_area.h"

src/vm_bitfont.c

@@ -1,5 +1,14 @@
 /*
  * vm_bitfont.c
+ *
+ * The bitfont code allows us to define and work with a bitmapped font.
+ * You can find the bitmap font glyphs in the `/fonts` subdir within the
+ * repository root, as well as bmp files that are compiled from those
+ * glyphs (via `/tools/build-fonts`).
+ *
+ * We do not have support for truetype fonts (nor other types of fonts)
+ * at this time, but the glyph system is pretty easy to work with, even
+ * if it is a hack.
  */
 
 #include "vm_bitfont.h"

src/vm_event.c

@@ -1,5 +1,10 @@
 /*
  * vm_event.c
+ *
+ * The code here handles events for the virtual machine; it essentially
+ * is a wrapper for SDL, presenting an interface to events that is
+ * independent of SDL itself. You would handle keyboard events here,
+ * mouse events, and more.
  */
 
 #include "vm_event.h"

src/vm_reflect.c

@@ -1,5 +1,9 @@
 /*
  * vm_reflect.c
+ *
+ * Here we have support for reflection, or perhaps meta-manipulation, of
+ * the virtual machine. You can create hooks to stop the machine, or
+ * disassemble opcodes from it, or handle state.
  */
 
 #include <stdlib.h>