some comments

src/ui.attract.mode.a

@@ -70,6 +70,13 @@ MiniAttractMode
          jsr   GetGameToLaunch
          +ST16 @GameToLaunch
 
+; We want to load the mini attract index into $800 so we can get the
+; index record for this game, but we now have so many games that the
+; entire index is larger than $1800 bytes and loading it all at once
+; would visibly overwrite bytes in HGR page 1. So the index is now
+; split into 2 halves based on the first letter of the game's
+; directory name, and we figure out which half we want and load it.
+
          +ST16 PTR
          ldy   #1
          lda   (PTR), y
@@ -90,6 +97,10 @@ MiniAttractMode
 @MiniAttractIndexRecord
          !word $FDFD                 ; SMC
 
+; Find the index record for this game and copy it into LC RAM so we
+; can reuse it without reloading the mini attract index over and over
+; during attract mode.
+
          jsr   okvs_find
          !word -
 @GameToLaunch
@@ -97,12 +108,14 @@ MiniAttractMode
          jsr   okvs_next_field
          jsr   SwitchToBank2
          sty   OKVS_CACHE
-         ldy   #4
+         ldy   #4                    ; length of index record (-1)
 -        lda   (PTR), y
          sta   OKVS_CACHE + 1, y
          dey
          bpl   -
 
+; Now, finally, start the mini attract mode
+
          jsr   BlankHGR
                                      ; X = 0
          stx   @MiniAttractIndex+1

src/ui.browse.mode.a

@@ -61,6 +61,9 @@ kBrowseQuit     = 11
 @j       jsr   $FDFD                 ; SMC
          jmp   @BrowseModeInputLoop
 
+;------------------------------------------------------------------------------
+; internal functions
+
 OnBrowseSearch
          sta   InputBuffer
          lda   #$01
@@ -124,8 +127,6 @@ BrowseHelpWrapper
          jsr   Help
          jmp   ForceBrowseChanged
 
-;------------------------------------------------------------------------------
-
 BrowseDispatchTableLo
          !byte <OnBrowseSearch
          !byte <OnBrowsePrevious

src/ui.overlay.a

@@ -277,7 +277,12 @@ gDrawingOnscreen=*+1
          jmp   ShowOtherDHGRPage
 +        jmp   ShowOtherPage
 
+;------------------------------------------------------------------------------
+; internal functions
+
 CheckCheats
+; out:   (SAVE) -> length-prefixed string, either a game-specific description
+;          or the global 'cheats enabled' message
          ldx   #kCheatsEnabled
          jsr   AnyGameSelected
          bcs   +
@@ -294,6 +299,13 @@ OVERLAYRTS
          rts
 
 MaybeRedrawUIForDHGR
+; If this is a DHGR title screen, then redraw the already-drawn overlay
+; for double hi-res. This allows us to use a single font and drawing
+; routines for both HGR and DHGR. There is a small amount of flicker
+; if we're redrawing directly on the visible screen without swapping
+; pages (e.g. adding a dot without changing the selected game), but
+; gDrawingOnscreen tracks this and we reduce the redrawing to an
+; absolute minimum to reduce flicker.
          bit   MachineStatus
          bvc   OVERLAYRTS
          bit   gGameToLaunchInfo