some comments

src/textrank.a

@@ -1,5 +1,5 @@
 ;license:MIT
-;(c) 2018-9 by 4am & qkumba
+;(c) 2018-2020 by 4am & qkumba
 ;
 ; text rank - an implementation of the Quicksilver search rank algorithm
 ;
@@ -11,6 +11,8 @@
 ; Public variables
 ; - InputLength                      ; [byte] number of characters typed in search mode
 ; - InputBuffer                      ; [25 bytes] characters typed in search mode
+;
+; Zero page variables
 ; - SelectedIndex                    ; [byte] index in gSearchStore of currently selected game in search mode
 ; - MatchCount                       ; [byte] number of games that match InputBuffer
 ; - BestMatchScore                   ; [byte] raw ranking score (0-100) of current best match (updated during TextRankCallback)
@@ -22,6 +24,17 @@ InputLength
 InputBuffer
          !text "                         "
 
+;------------------------------------------------------------------------------
+; BuildSearchStore
+; Build a temporary data structure in main memory to support search UI.
+; Now that gGamesListStore no longer contains full game display names, we call
+; this to build a store that does. It's built in main memory and will be
+; clobbered as soon as we enter attract mode (mega- or mini-), run a game,
+; run a demo, or sneeze.
+;
+; in:    none
+; out:   gSearchStore populated
+;------------------------------------------------------------------------------
 BuildSearchStore
          jsr   SwitchToBank2
          jsr   EnableAcceleratorAndSwitchToBank1

src/ui.attract.dhgr.a

@@ -9,8 +9,9 @@
 ; - DHGRSingle
 ; - BlankHGR
 ; - HGRMode
-; - ForceHGRMOde
+; - GRMode
-; - DrawGameTitleInActionSlideshowHGR
+; - ForceHGRMode
+; - DrawGameTitleInActionSlideshow
 ; - RedrawForDHGR
 ;
 
@@ -97,8 +98,8 @@ BlankHGR
          sta   OffscreenPage
          ; /!\ execution falls through here to HGRMode
 ;------------------------------------------------------------------------------
-; HGRMode
+; HGRMode / GRMode
-; twiddles softswitches to set HGR mode (does not set page 1 or 2)
+; twiddles softswitches to set (H)GR mode (does not set page 1 or 2)
 ;
 ; in:    none
 ; out:   all registers preserved
@@ -233,7 +234,18 @@ DHGRActionCallback
 
          lda   #$EA                  ; NOP
          +HIDE_NEXT_2_BYTES
-DrawGameTitleInActionSlideshowHGR
+         ; /!\ execution falls through here to DrawGameTitleInActionSlideshowHGR
+;------------------------------------------------------------------------------
+; DrawGameTitleInActionSlideshow
+; draw the game title in the lower left corner of the screen
+;
+; /!\ exits via ExecuteTransitionAt6000AndWait, and the transition code must
+;     already be loaded at $6000
+;
+; in:    none
+; out:   exits via ExecuteTransitionAt6000AndWait
+;------------------------------------------------------------------------------
+DrawGameTitleInActionSlideshow
          lda   #$60                  ; RTS
          sta   @fallthroughForDHGR
 

src/ui.attract.gr.a

@@ -44,7 +44,7 @@ GRSingle
          jmp   BlankHGR              ; switch back to HGR mode with initial blank screen on exit
 
 ;------------------------------------------------------------------------------
-; BlankGR
+; BlankGR [private]
 ; clear and show GR page 1 without flickering
 ;
 ; in:    none
@@ -63,7 +63,7 @@ BlankGR
          jmp   GRMode
 
 ;------------------------------------------------------------------------------
-; .LoadGRTransition [private]
+; LoadGRTransition [private]
 ;
 ; in:    none
 ; out:   all registers and flags clobbered
@@ -78,7 +78,7 @@ LoadGRTransition
 GRRTS    rts
 
 ;------------------------------------------------------------------------------
-; .GRActionCallback [private]
+; GRActionCallback [private]
 ; callback called by okvs_iter on gSlideshowStore
 ; to load and display a single GR action screenshot
 

src/ui.attract.hgr.a

@@ -163,4 +163,4 @@ HGRActionCallback
 +        !word $FDFD                 ; SMC
          !word $3FF8
          jsr   DecompressHGR
-         jmp   DrawGameTitleInActionSlideshowHGR
+         jmp   DrawGameTitleInActionSlideshow

src/ui.attract.shr.a

@@ -58,6 +58,7 @@ SHRSingle
 
 ;------------------------------------------------------------------------------
 ; LoadSHGRTransition [private]
+; load the SHR transition effect code (currently always the same file)
 ;
 ; in:    none
 ; out:   all registers and flags clobbered

src/ui.wait.a

@@ -10,7 +10,6 @@
 ; - WaitForKeyFor30Seconds
 ; - CoverFade
 
-         ; /!\ execution falls through here from ui.attract.dhgr/DHGRActionCallback
 ExecuteTransitionAt6000AndWait
          ldy   #$60
          +HIDE_NEXT_2_BYTES