some comments

src/ui.animation.a

@@ -3,15 +3,25 @@
 ;
 ; functions for animated title screens
 ;
+; Public functions:
 ; - MaybeAnimateTitle
 ;
 
          ; /!\ execution falls through from ui.search.mode/FindMatchingTitle
+;------------------------------------------------------------------------------
+; MaybeAnimateTitle
+; slow down to 1 Mhz (always), then check if there is an animation for the
+; title screenshot we just displayed, and if so, load it and call it
+;
+; in:    none
+; out:   C clear
+;        all other flags clobbered
+;        all registers clobbered
+;------------------------------------------------------------------------------
 MaybeAnimateTitle
          jsr   SwitchToBank2
          jsr   DisableAcceleratorAndSwitchToBank1
 
-; out:   C clear
          lda   #$3F
          ldy   OffscreenPage
          bne   +
@@ -26,7 +36,13 @@ MaybeAnimateTitle
          ldy   #0
          lda   (SAVE),y              ; see if there is a hidden JMP to an
          cmp   #$4C                  ; animation routine for this screen
-         bne   @exit
+                                     ; at +$1FFD (after the graphics data,
+                                     ; in the last 3 bytes of a $2000 byte
+                                     ; file -- this area part of a 'screen
+                                     ; hole' and is not displayed on screen)
+         bne   @exit                 ; if not, we're done here
+
+         ; copy one HGR screen to the other
          ldx   #$20
 @a       lda   $FD00,y               ; SMC
 @b       sta   $FD00,y               ; SMC
@@ -37,8 +53,8 @@ MaybeAnimateTitle
          dex
          bne   @a
 
-         jsr   GetGameToLaunch       ; load the animation routine, which is
+         ; load the animation routine, which is stored in a subdirectory by filename
-                                     ; stored in a subdirectory by filename
+         jsr   GetGameToLaunch
          +STAY +
          jsr   LoadFile
          !word kAnimatedTitleDirectory
@@ -51,11 +67,16 @@ MaybeAnimateTitle
          dex
          bpl   -
 
-         jsr   Launch
+         jsr   Launch                ; execute the animation
-         jsr   ResyncPage
+
+         jsr   ResyncPage            ; we don't know which HGR page is showing
+                                     ; when the animation returns, so resync
+                                     ; the current one with our OffscreenPage
+                                     ; variable
+
 @exit    clc                         ; tell caller not to refresh screen
          rts
 
-@titleAnimPrelaunch
+@titleAnimPrelaunch                  ; this is executed from $106/main by |Launch|
          bit   $C082
          jmp   (SAVE)

src/ui.attract.dhgr.a

@@ -11,6 +11,16 @@
 ; - HGRMode
 ;
 
+;------------------------------------------------------------------------------
+; DHGRTitleSlideshow
+; execute a slideshow of double hi-res title screenshots
+;
+; safe to call if machine only has 64K (does nothing and exits)
+;
+; in:    none
+; out:   everything clobbered
+;        graphics mode reset to display hi-res screen, which is blank
+;------------------------------------------------------------------------------
 DHGRTitleSlideshow
          bit   MachineStatus         ; only run DHGR slideshow if we have 128K
          bvc   DHGRRTS
@@ -22,6 +32,16 @@ DHGRTitleSlideshow
          beq   BlankHGR              ; switch back to HGR mode with initial blank screen on exit
                                      ; (always branches because Z=1 on exit of okvs_iter)
 
+;------------------------------------------------------------------------------
+; DHGRActionSlideshow
+; execute a slideshow of double hi-res action screenshots
+;
+; safe to call if machine only has 64K (does nothing and exits)
+;
+; in:    none
+; out:   everything clobbered
+;        graphics mode reset to display hi-res screen, which is blank
+;------------------------------------------------------------------------------
 DHGRActionSlideshow
          bit   MachineStatus         ; only run DHGR slideshow if we have 128K
          bvc   DHGRRTS
@@ -33,6 +53,16 @@ DHGRActionSlideshow
          beq   BlankHGR              ; switch back to HGR mode with initial blank screen on exit
                                      ; (always branches because Z=1 on exit of okvs_iter)
 
+;------------------------------------------------------------------------------
+; DHGRSingle
+; display a single double hi-res screenshot, with transition effect
+;
+; safe to call if machine only has 64K (does nothing and exits)
+;
+; in:    none
+; out:   everything clobbered
+;        graphics mode reset to display hi-res screen, which is blank
+;------------------------------------------------------------------------------
 DHGRSingle
          bit   MachineStatus         ; only show DHGR screenshots if we have 128K
          bvc   DHGRRTS

src/ui.attract.gr.a

@@ -8,6 +8,14 @@
 ; - GRSingle
 ;
 
+;------------------------------------------------------------------------------
+; GRActionSlideshow
+; display a slideshow of lo-res action screenshots
+;
+; in:    none
+; out:   everything clobbered
+;        graphics mode set to display hi-res screen
+;------------------------------------------------------------------------------
 GRActionSlideshow
          jsr   .LoadGRTransition     ; load transition effect code at $6000
          jsr   BlankGR               ; switch GR mode with initial blank screen
@@ -16,6 +24,14 @@ GRActionSlideshow
          !word .GRActionCallback     ; address of callback (called on each file)
          jmp   BlankHGR              ; switch back to HGR mode with initial blank screen on exit
 
+;------------------------------------------------------------------------------
+; GRSingle
+; display a single lo-res screenshot, with transition effect
+;
+; in:    none
+; out:   everything clobbered
+;        graphics mode set to display hi-res screen
+;------------------------------------------------------------------------------
 GRSingle
          +STAY @fname
          jsr   BlankGR               ; switch to GR mode with initial blank screen
@@ -33,6 +49,7 @@ GRSingle
 ;
 ; in:    none
 ; out:   text page clobbered
+;        graphics mode set to display lo-res screen
 ;------------------------------------------------------------------------------
 BlankGR
          ldx   #$04

src/ui.attract.hgr.a

@@ -9,6 +9,14 @@
 ; - HGRSingle
 ;
 
+;------------------------------------------------------------------------------
+; HGRTitleSlideshow
+; execute a slideshow of hi-res title screenshots
+;
+; in:    none
+; out:   everything clobbered
+;        graphics mode still displaying hi-res screen with last picture visible
+;------------------------------------------------------------------------------
 HGRTitleSlideshow
          jsr   LoadHGRTransition     ; load transition effect code at $6000
          jsr   okvs_iter             ; cycle through all listed HGR files
@@ -16,6 +24,14 @@ HGRTitleSlideshow
          !word HGRTitleCallback      ; address of callback (called on each file)
          rts                         ; exit with last picture still visible
 
+;------------------------------------------------------------------------------
+; HGRActionSlideshow
+; execute a slideshow of hi-res action screenshots
+;
+; in:    none
+; out:   everything clobbered
+;        graphics mode still displaying hi-res screen with last picture visible
+;------------------------------------------------------------------------------
 HGRActionSlideshow
          jsr   LoadHGRTransition     ; load transition effect code at $6000
          jsr   okvs_iter             ; cycle through all listed HGR files
@@ -23,6 +39,14 @@ HGRActionSlideshow
          !word HGRActionCallback     ; address of callback (called on each file)
          rts                         ; exit with last picture still visible
 
+;------------------------------------------------------------------------------
+; HGRSingle
+; display a single hi-res screenshot, with transition effect
+;
+; in:    none
+; out:   everything clobbered
+;        graphics mode still displaying hi-res screen with last picture visible
+;------------------------------------------------------------------------------
 HGRSingle
          +STAY @fname
          jsr   LoadFile              ; load HGR screenshot at $4000

src/ui.attract.shr.a

@@ -8,6 +8,17 @@
 ; - SHRSingle
 ;
 
+;------------------------------------------------------------------------------
+; SHRSlideshow
+; execute a slideshow of super hi-res artwork
+;
+; safe to call if machine can not display super hi-res graphics (does nothing
+; and exits)
+;
+; in:    none
+; out:   everything clobbered
+;        graphics mode reset to display hi-res screen, which is blank
+;------------------------------------------------------------------------------
 SHRSlideshow
          lda   MachineStatus         ; only show SHR on IIgs or if we have a VidHD card
          and   #SUPPORTS_SHR
@@ -19,6 +30,17 @@ SHRRTS   rts
          !word SHRArtworkCallback
          jmp   BlankHGR
 
+;------------------------------------------------------------------------------
+; SHRSlideshow
+; display a single super hi-res artwork
+;
+; safe to call if machine can not display super hi-res graphics (does nothing
+; and exits)
+;
+; in:    none
+; out:   everything clobbered
+;        graphics mode reset to display hi-res screen, which is blank
+;------------------------------------------------------------------------------
 SHRSingle
          +STAY +
          lda   MachineStatus         ; only show SHR on IIgs or if we have a VidHD card
@@ -48,7 +70,7 @@ LoadSHRTransition
          rts
 
 ;------------------------------------------------------------------------------
-; .SHRArtworkCallback [private]
+; SHRArtworkCallback [private]
 ; callback called by okvs_iter on gSlideshowStore
 ; to load and display a single SHR graphic
 
@@ -83,7 +105,7 @@ SHRArtworkCallback
          jmp   ExecuteTransitionAtA000AndWait
 
 ;------------------------------------------------------------------------------
-; .BlankSHR [private]
+; BlankSHR [private]
 ; clear and show SHR mode without flickering
 ;
 ; in:    Machine is a IIgs or has a VidHD card that responds appropriately to

src/ui.cheats.a

@@ -7,10 +7,19 @@
 ; - ToggleCheat
 ;
 
-ToggleCheat
+;------------------------------------------------------------------------------
+; ToggleCheat
+; toggle whether cheats are enabled (global flag) and update the preferences
+; file with the new status
+;
+; does not update UI
+;
 ; in:    none
-; out:   X = 0, Z = 1 (guaranteed by pref_set)
+; out:   X = 0
+;        Z = 1
 ;        all other registers and flags clobbered
+;------------------------------------------------------------------------------
+ToggleCheat
          ldx   #$B0
          lda   MachineStatus
          eor   #CHEATS_ENABLED
@@ -22,6 +31,7 @@ ToggleCheat
          jsr   pref_set
          !word kCheat
          !word @pref
+                                     ; X = 0, Z = 1
          rts
 @pref    !byte 1
 @val     !byte $FD

src/ui.common.a

@@ -128,6 +128,16 @@ IsSearchKey
          ldx   #1
          rts
 
+;------------------------------------------------------------------------------
+; IsUpDownOrRightArrow
+; test whether accumulator contains ASCII code for up, down, or right arrow
+; search
+;
+; in:    A = key
+; out:   all registers preserved
+;        Z = 1 if accumulator was one of those 3 keys
+;        Z = 0 otherwise
+;------------------------------------------------------------------------------
 IsUpDownOrRightArrow
          cmp   #$8B                  ; up arrow
          beq   @done

src/ui.credits.a

@@ -8,8 +8,15 @@
 ; - Help
 ;
 
+;------------------------------------------------------------------------------
+; Credits
+; display credits page and wait
+;
+; in:    none
+; out:   C clear
+;        all other flags and registers clobbered
+;------------------------------------------------------------------------------
 Credits
-; clobbers all
          jsr   LoadFile              ; load credits text into $8000
          !word kRootDirectory
          !word kCreditsFile
@@ -26,8 +33,16 @@ Credits
 -        clc                         ; if called from search mode, tell caller not to refresh
          rts
 
+;------------------------------------------------------------------------------
+; Help
+; display global help page and wait
+;
+; in:    none
+; out:   if user presses an arrow key within 30 seconds, this exits via BrowseMode
+;        otherwise this returns to caller with
+;          C clear, all other flags and registers clobbered
+;------------------------------------------------------------------------------
 Help
-; clobbers all
          jsr   LoadHelpOffscreen
          jsr   ShowOtherPage
          jsr   WaitForKeyFor30Seconds

src/ui.wait.a

@@ -3,10 +3,14 @@
 ;
 ; UI functions for doing things then waiting, or waiting then doing things
 ;
+; - ExecuteTransitionAt6000AndWait
+; - ExecuteTransitionAt6400AndWait
+; - ExecuteTransitionAtA000AndWait
 ; - ExecuteTransitionAndWait
 ; - WaitForKeyFor30Seconds
 ; - CoverFade
 
+         ; /!\ execution falls through here from ui.attract.dhgr/DHGRActionCallback
 ExecuteTransitionAt6000AndWait
          ldy   #$60
          +HIDE_NEXT_2_BYTES
@@ -15,8 +19,7 @@ ExecuteTransitionAt6400AndWait
          +HIDE_NEXT_2_BYTES
 ExecuteTransitionAtA000AndWait
          ldy   #$A0
-
+         ; /!\ execution falls through here to ExecuteTransitionAndWait
-         ; /!\ execution falls through here from ui.attract.dhgr/DHGRActionCallback
 ;------------------------------------------------------------------------------
 ; ExecuteTransitionAndWait
 ; call transition effect code (address passed in) and wait a period of time
@@ -41,7 +44,6 @@ ExecuteTransitionAndWait
          bit   CLEARKBD
 WAITRTS  rts
 
-; /!\ keep this last in the file to ensure it doesn't cross a page boundary /!\
 ;------------------------------------------------------------------------------
 ; WaitForKeyFor30Seconds
 ; does what it says on the tin
@@ -71,6 +73,13 @@ WaitForKeyFor30Seconds
          dec   Timeout+2
          bne   @loop
          ; /!\ execution falls through here to CoverFade
+;------------------------------------------------------------------------------
+; CoverFade
+; load cover file and execute a specific transition effect on it
+;
+; in:    none
+; out:   exits via MegaAttractMode and everything is clobbered
+;------------------------------------------------------------------------------
 CoverFade
          jsr   LoadCoverOffscreen
          jsr   ShowOtherPage