some comments

src/storage.a

@@ -8,7 +8,6 @@
 ; - LoadProgressFromDisk
 ; - LoadProgressFromMemory
 ; - LoadPuzzleFromMemory
-; - HasPuzzleBeenCompleted
 ; - MarkPuzzleCompleted
 ; - FindPackedProgressAddr
 ;
@@ -243,24 +242,6 @@ LoadPuzzleFromMemory
          !byte 40
          !raw  "                                        "
 
-;------------------------------------------------------------------------------
-; HasPuzzleBeenCompleted
-;
-; in:    X = puzzle ID
-; out:   C clear if puzzle had previously been marked as completed
-;        C set if puzzle has never been marked as completed
-;        X/Y preserved
-;        A clobbered
-;        other flags clobbered
-;------------------------------------------------------------------------------
-HasPuzzleBeenCompleted
-         lda   PROGRESS, x
-         beq   +
-         clc
-         rts
-+        sec
-         rts
-
 ;------------------------------------------------------------------------------
 ; MarkPuzzleCompleted
 ;

src/ui.about.a

@@ -59,9 +59,14 @@ kAboutMockingDuet
          !byte 35
          !raw "MOCKINGBOARD ROUTINES BY CYBERNESTO"
 
-AboutPage
+;------------------------------------------------------------------------------
+; AboutPage
+; display animated credits page
+;
 ; in:    none
-; out:   everything clobbered
+; out:   all registers & flags clobbered
+;------------------------------------------------------------------------------
+AboutPage
          jsr   Home
 @outerloop
          lda   #0

src/ui.common.a

@@ -20,12 +20,17 @@
 GlobalLeftMargin
          !byte $0A
 
-Home
+;------------------------------------------------------------------------------
+; Home
+; clear graphics page 1 without flicker
+;
 ; in:    none, but assumes text screen 1 is clear (this is done at program startup)
 ; out:   hi-res page 1 cleared and displayed
 ;        X preserved
 ;        A/Y clobbered
 ;        flags clobbered
+;------------------------------------------------------------------------------
+Home
          bit   PAGE1
          bit   FULLGFX
          bit   HIRES
@@ -69,10 +74,15 @@ Home
          bit   GFXMODE
          rts
 
-WaitForKeyWithTimeout
+;------------------------------------------------------------------------------
+; WaitForKeyWithTimeout
+; just what it says on the tin
+;
 ; in:    A = timeout length (like standard $FCA8 wait routine)
-; out:   A clobbered
+; out:   A = 0
 ;        X/Y preserved
+;------------------------------------------------------------------------------
+WaitForKeyWithTimeout
          sec
 @wait1   pha
 @wait2   sbc   #1
@@ -84,12 +94,26 @@ WaitForKeyWithTimeout
          bne   @wait1
 @exit    rts
 
+;------------------------------------------------------------------------------
+; ScrollDown
+; scroll a single puzzle column down 16 HGR rows
+;
+; in:    Y = logical column to scroll
+; out:   X/Y preserved
+;------------------------------------------------------------------------------
 ScrollDown
          lda   #$16
-ScrollDownBy
+         ; /!\ execution falls through to ScrollDownBy
+
+;------------------------------------------------------------------------------
+; ScrollDownBy
+; scroll a single puzzle column down a specified number of HGR rows
+;
 ; in:    Y = logical column to scroll
 ;        A = number of HGR rows to scroll
 ; out:   X/Y preserved
+;------------------------------------------------------------------------------
+ScrollDownBy
          stx   @x+1
          sty   @y+1
          tax
@@ -100,12 +124,26 @@ ScrollDownBy
 @y       ldy   #$FD                  ; SMC
          rts
 
+;------------------------------------------------------------------------------
+; ScrollUp
+; scroll a single puzzle column up 16 HGR rows
+;
+; in:    Y = logical column to scroll
+; out:   X/Y preserved
+;------------------------------------------------------------------------------
 ScrollUp
          lda   #$16
-ScrollUpBy
+         ; /!\ execution falls through to ScrollUpBy
+
+;------------------------------------------------------------------------------
+; ScrollUpBy
+; scroll a single puzzle column up a specified number of HGR rows
+;
 ; in:    Y = logical column to scroll
 ;        A = number of HGR rows to scroll
 ; out:   X/Y preserved
+;------------------------------------------------------------------------------
+ScrollUpBy
          stx   @x+1
          sty   @y+1
          tax
@@ -116,20 +154,15 @@ ScrollUpBy
 @y       ldy   #$FD                  ; SMC
          rts
 
-InitScrollStorage
+;------------------------------------------------------------------------------
-; out:   preserves X/Y
+; LogicalColumnToPhysicalColumn
-         lda   #$00
+;
-         sta   $FC
-         sta   $FD
-         sta   $FE
-         sta   $FF
-         rts
-
-LogicalColumnToPhysicalColumn
 ; in:    Y contains logical column number
 ; out:   Y contains physical byte offset to use against an HGR base address
 ;        A clobbered
 ;        X preserved
+;------------------------------------------------------------------------------
+LogicalColumnToPhysicalColumn
          lda   GlobalLeftMargin
          clc
          bcc   +
@@ -141,14 +174,19 @@ LogicalColumnToPhysicalColumn
 
 nonZeroDigits = $EE
 paddingCharacter = $EF
-ToASCIIString
+;------------------------------------------------------------------------------
-; convert byte value to length-prefixed 3-digit decimal number as ASCII string with given padding character
+; ToASCIIString
+; convert byte value to length-prefixed 3-digit decimal number as ASCII string
+; with given padding character
+;
 ; in:    X = any number (0..255 obviously)
 ;        A = padding character (e.g. '0' or ' ')
 ; out:   $F1 = 0x03
 ;        $F2..$F4 = ASCII digits of decimal representation
 ;        clobbers $EE,$EF,$F0
 ;        all flags & registers clobbered
+;------------------------------------------------------------------------------
+ToASCIIString
          sta   paddingCharacter
          stx   $F0
          ldx   #0
@@ -191,3 +229,13 @@ ToASCIIString
          !byte 100
          !byte 10
          !byte 1
+
+InitScrollStorage
+; [private]
+; out:   preserves X/Y
+         lda   #$00
+         sta   $FC
+         sta   $FD
+         sta   $FE
+         sta   $FF
+         rts

src/ui.font.courier.double.prime.a

@@ -3,6 +3,9 @@
 ;
 ; font drawing routines
 ;
+; Public functions:
+; - DrawLargeCharacter
+;
 
 !macro COMPUTE_DRAW_ADDRESSES {
          ldx   charrow
@@ -22,17 +25,21 @@
          +COMPUTE_DRAW_ADDRESSES
 }
 
+;------------------------------------------------------------------------------
+; DrawLargeCharacter
+;
+; in:    A contains character (0x41..0x5A) or 0x00
+;        X contains logical line number (0x00..0x08)
+;        Y contains logical column number (0x00..0x0C)
+;        HGR row is (0x16 * X)
+;          which needs to total no more than 0xB0
+;        character will be drawn on HGR row, byte offset (GlobalLeftMargin + (3 * Y))
+;          which needs to total no more than 0x26
+; out:   preserves X/Y
+;        clobbers A/all flags
+;        clobbers $ED..$F7
+;------------------------------------------------------------------------------
 DrawLargeCharacter
-; A contains character (0x41..0x5A) or 0x00
-; X contains logical line number (0x00..0x08)
-; Y contains logical column number (0x00..0x0C)
-; HGR row is (0x16 * X)
-;   which needs to total no more than 0xB0
-; character will be drawn on HGR row, byte offset (GlobalLeftMargin + (3 * Y))
-;   which needs to total no more than 0x26
-; preserves X/Y
-; clobbers A/all flags
-; clobbers $ED..$F7
          sta   original_char
          beq   +
          and   #$7F

src/ui.font.heavy.silk.a

@@ -3,15 +3,25 @@
 ;
 ; font drawing routines for Heavy Silk pixel font
 ;
+; Public functions:
+; - DrawHeavySilkString
+; - DrawHeavySilkBuffer
+; - DrawHeavySilkBufferInverse
+;
 
+;------------------------------------------------------------------------------
+; DrawLargeCharacter
+;
+; in:    A/Y contains address of length-prefixed string (length 1..40,
+;          characters 0x20..0x5A only)
+;        $24 (HTAB) contains starting column (0..39)
+;        $25 (VTAB) contains textpage line (0..23)
+;        all characters are drawn on the same line
+;        HTAB is incremented for each character
+; out:   clobbers A/X/Y
+;        clobbers $FE/$FF
+;------------------------------------------------------------------------------
 DrawHeavySilkString
-; A/Y contains address of length-prefixed string (length 1..40, characters 0x20..0x5A only)
-; $24 (HTAB) contains starting column (0..39)
-; $25 (VTAB) contains textpage line (0..23)
-; all characters are drawn on the same line
-; HTAB is incremented for each character
-; clobbers A/X/Y
-; clobbers $FE/$FF
          +ST16 $FE
          ldy   #0
          lda   ($FE),y
@@ -23,15 +33,19 @@ DrawHeavySilkString
          +LD16 $FE
          ; /!\ execution falls through here to DrawHeavySilkBuffer
 
+;------------------------------------------------------------------------------
+; DrawHeavySilkBuffer
+;
+; in:    A/Y contains address of character buffer (characters 0x20..0x5A only)
+;        X contains buffer length (1..40)
+;        $24 (HTAB) contains starting column (0..39)
+;        $25 (VTAB) contains textpage line (0..23)
+;        all characters are drawn on the same line
+;        HTAB is incremented for each character
+;        VTAB is NOT incremented
+; out:   clobbers A/X/Y
+;------------------------------------------------------------------------------
 DrawHeavySilkBuffer
-; A/Y contains address of character buffer (characters 0x20..0x5A only)
-; X contains buffer length (1..40)
-; $24 (HTAB) contains starting column (0..39)
-; $25 (VTAB) contains textpage line (0..23)
-; all characters are drawn on the same line
-; HTAB is incremented for each character
-; VTAB is NOT incremented
-; clobbers A/X/Y
          +ST16 @loop+1
          dex
          lda   VTAB
@@ -91,15 +105,19 @@ DrawHeavySilkBuffer
          bpl   @loop
          rts
 
+;------------------------------------------------------------------------------
+; DrawHeavySilkBufferInverse
+;
+; in:    A/Y contains address of character buffer (characters 0x20..0x5A only)
+;        X contains buffer length (1..40)
+;        $24 (HTAB) contains starting column (0..39)
+;        $25 (VTAB) contains textpage line (0..23)
+;        all characters are drawn on the same line
+;        HTAB is incremented for each character
+;        VTAB is NOT incremented
+; out:   clobbers A/X/Y
+;------------------------------------------------------------------------------
 DrawHeavySilkBufferInverse
-; A/Y contains address of character buffer (characters 0x20..0x5A only)
-; X contains buffer length (1..40)
-; $24 (HTAB) contains starting column (0..39)
-; $25 (VTAB) contains textpage line (0..23)
-; all characters are drawn on the same line
-; HTAB is incremented for each character
-; VTAB is NOT incremented
-; clobbers A/X/Y
          +ST16 @loop+1
          dex
          lda   VTAB

src/ui.help.a

@@ -55,6 +55,14 @@ help_esc
          !byte 40
          !raw  "ESC............................MAIN MENU"
 
+;------------------------------------------------------------------------------
+; HelpEventLoop
+; display help subpage
+;
+; in:    none
+; out:   C = 1
+;        all other flags & registers clobbered
+;------------------------------------------------------------------------------
 HelpEventLoop
          jsr   Home
          jsr   DrawHelpText
@@ -66,6 +74,7 @@ HelpEventLoop
          rts
 
 DrawHelpText
+; [private]
          bit   TEXTMODE
          +PRINT_AT help_info1, 3, 7
          +PRINT_AT help_info2, 5, 7

src/ui.interstitial.a

@@ -85,13 +85,18 @@ kEmptyString
          !byte 1
          !raw " "
 
-MaybeShowInterstitial
+;------------------------------------------------------------------------------
+; MaybeShowInterstitial
+; display interstitial progress animation after every 10 completed puzzles
+;
 ; in:    A = next puzzle ID (in this world)
 ;        X = # of puzzles completed (in this world)
 ; out:   preserves A
 ;        C set if all puzzles were completed
 ;        C clear if there are more puzzles in this world (and A = next puzzle ID)
 ;        Y, other flags clobbered
+;------------------------------------------------------------------------------
+MaybeShowInterstitial
          pha
          cpx   #100
          bne   +
@@ -120,6 +125,7 @@ MaybeShowInterstitial
 
 ShowInterstitialWorldProgress
 ShowInterstitialWorldComplete
+; [private]
 ; in:    Y = which progress string to display (1..9)
 ; out:   all registers and flags clobbered
          bit   CLEARKBD

src/ui.main.menu.a

@@ -1,10 +1,10 @@
 ;license:MIT
 ;(c) 2020 by 4am
 ;
-; main menu
+; main menu & select world screen
 ;
 ; Public functions:
-; - MainMenu
+; - MainMenuEventLoop
 ;
 
 ; Codes returned by event handlers
@@ -44,7 +44,10 @@ kMainMenuKeyHandlersHi
          !byte >MainMenuEventQ
          !byte >MainMenuEventQ
 
-MainMenuEventLoop
+;------------------------------------------------------------------------------
+; MainMenuEventLoop
+; display main menu
+;
 ; in:    C clear if screen is already cleared and title is already drawn
 ;          (will happen if animated title screen runs to completion)
 ;        C set if full screen clear & redraw is required
@@ -53,6 +56,8 @@ MainMenuEventLoop
 ; out:   C clear if user selected a world to play, and
 ;          A = world ID
 ;        C set if user selected quit
+;------------------------------------------------------------------------------
+MainMenuEventLoop
          bcc   +
          jsr   DrawMainMenuTitle
 +        jsr   DrawMainMenuText
@@ -155,6 +160,7 @@ counter = $F2
 selectedworld = $F3
 
 SelectWorld
+; [private]
 ; in:    none
 ; out:   C clear if world was selected, and
 ;          A = 0-based world ID

src/unused.a

@@ -0,0 +1,17 @@
+;------------------------------------------------------------------------------
+; HasPuzzleBeenCompleted
+;
+; in:    X = puzzle ID
+; out:   C clear if puzzle had previously been marked as completed
+;        C set if puzzle has never been marked as completed
+;        X/Y preserved
+;        A clobbered
+;        other flags clobbered
+;------------------------------------------------------------------------------
+HasPuzzleBeenCompleted
+         lda   PROGRESS, x
+         beq   +
+         clc
+         rts
++        sec
+         rts