some comments (no code changes)

src/apidefs.a

@@ -1,3 +1,12 @@
+;-------------------------------
+; Global constants, addresses, and other sundries
+;
+; /!\ Everything after APIEND must be kept in sync
+;     with apidefs.a!
+;
+; /!\ NO CODE IN THIS FILE, NO EXCEPTIONS
+;-------------------------------
+
 TRUE     =     $00        ; Lots of code assumes this is zero
                           ; so it can branch with BEQ, so
                           ; don't change it!

src/cffa.a

@@ -1,3 +1,15 @@
+;-------------------------------
+; EnterCFFAIfAvailable
+; check for, and potentially call, the CFFA 3000
+; administration menu
+;
+; currently only supports CFFA 3000 in slot 7
+; (no slot scan)
+;
+; in:    none
+; out:   C clear if we found CFFA 3000 in slot 7 and called it
+;        C set if we didn't find CFFA 3000
+;-------------------------------
 EnterCFFAIfAvailable
          ldy   #$04
 -        lda   $C7F6, y

src/crackme.a

@@ -1,3 +1,18 @@
+;-------------------------------
+; ReadWithRWTS
+; This is the main loop. The caller has put an RWTS
+; in place -- either by boot tracing or by starting
+; with the built-in RWTS and patching -- and now it's
+; time to do the thing. This routine reads the source
+; disk, applies patches in memory, maybe writes out
+; the result (depending on mode), and prints relevant
+; log messages along the way.
+;
+; in:    suitable RWTS is in place
+;        relevant globals from ID phase have been set
+; out:   all registers clobbered
+;        exits via TheEnd
+;-------------------------------
 ReadWithRWTS
          jsr   IncProgress
          lda   #$22
@@ -137,7 +152,11 @@ nextsector
          ldy   gTrack
          dey
          tya
-         jsr   ChangeTrack
+         jsr   ChangeTrack           ; in crack mode, this calls WriteTrack
+                                     ; which calls AnalyzeTrack to apply patches,
+                                     ; then (if we're not using a RAM disk)
+                                     ; actually writes the track to the target
+                                     ; disk or file
          jsr   IncProgress
          lda   gTrack
          bmi   Pass

src/keys.a

@@ -1,3 +1,13 @@
+;-------------------------------
+; WaitForKey
+; wait forever for a key
+; if the key pressed is '*', break to the monitor
+; with a message on how to get back
+;
+; in:    none
+; out:   A = uppercase version of key pressed
+;        other flags and registers clobbered
+;-------------------------------
 WaitForKey
          bit   STROBE
 -        lda   KEY

src/print.a

@@ -1,8 +1,13 @@
 ;-------------------------------
 ; PrintByID
 ; Print a string from the string table
+;
 ; Handles string substitutions and
 ; auto-uppercases on older machines
+;
+; fully re-entrant to support nested
+; string substitutions (see strings/en.a)
+;
 ; in:    string ID (byte) on stack
 ; out:   all registers preserved
 ;        oVerflow bit clear

src/slots.a

@@ -1,5 +1,30 @@
 ;-------------------------------
-; NextSlot
+; NextSlot/ThisSlot
+; cycle through available output targets
+;
+; This is more complicated than it used to be,
+; because we now support writing to files on suitable
+; hard disks. But the purpose of this routine is to
+; encapsulate all that messiness and set the relevant
+; globals (SLOT, DRIVE, gTargetType) to values the
+; caller can rely on without any additional checks.
+;
+; ThisSlot is an alternate entry point that is called
+; once during program startup, to set the initial slot
+; and drive and target type. The initial values may
+; have been read from a preferences file, which may not
+; accurately reflect the current environment (e.g. the
+; previous target drive may have disappeared since the
+; preferences file was written). In this case, calling
+; ThisSlot ends up being equivalent to calling NextSlot,
+; but the caller doesn't need to care about it one way
+; or the other. (If ThisSlot ends up having to change
+; the slot or drive, it does NOT set gChangedPrefs to
+; TRUE. This is an intentional design decision, on which
+; you are welcome to have an opinion as long as you keep
+; it to yourself. Just kidding, nobody has ever even
+; thought about this except me.)
+;
 ; in:    DiskIIArray populated by calling ScanForDiskII
 ;        HardDiskArray populated by calling ScanForRAMAndHardDisks
 ; out:   @SLOT, @DRIVE set to ASCII values of next available slot/drive

src/wholetrack.a

@@ -1,3 +1,21 @@
+;-------------------------------
+; Identification routines for various whole-track
+; protections and other frivolities.
+;
+; The main entry point is SkipTrack, which is
+; called when the last sector ($0F or $0C) of a
+; newly-seeked track is unexpectedly unreadable.
+; (All the words in that sentence are important.)
+;
+; This file also contains low-level subroutines
+; that require precise timing. There are
+; assemble-time guards around the timing-sensitive
+; instructions, which means that changes to this
+; file may result in fatal assembler build errors
+; because you moved code that can't cross a page
+; boundary and now it crosses a page boundary.
+;-------------------------------
+
 ;-------------------------------
 ; SkipTrack
 ; out:   C clear if we should skip this track