fx@3.10: intuitions about the GetKeyWait dispatcher

asm/fx@3.10-GetKeyWait_Dispatcher.txt

@@ -1,3 +1,43 @@
+This "Dispatcher" function is at the center of a weird scheme involving jump
+buffers inside GetKeyWait.
+
+The GetKeyWait function (conditionally) starts by a call to setjmp()
+immediately followed by a call to this dispatcher, passing along the return
+value of the long jump, which has 12 values, as we'll see shortly.
+
+There are two jump buffers in GetKeyWait, and which one is used depends on a
+RAM global that changes value several times along the execution. Hence, the
+*state* of this scheme consists of:
+
+-> Which buffer is currently selected;
+-> The return value of the long jump.
+
+I believe that the scheme is best viewed as a finite state machine, where each
+state change triggers a return to the start of GetKeyWait().
+
+This Dispatcher function implements some of the logic of that state machine.
+It starts with a jump-table-based switch which executes code depending on the
+return value of the long jump. The executed code does things like:
+
+* Change the currently-selected buffer and return, letting GetKeyWait execute
+* Change the currently-seletced buffer and long jump back, changing the long
+  jump return code and forcing an immediate return to the dispatcher
+* Read and write the state of the SHIFT and ALHA modifiers (even though that is
+  normally handled by GetKey()?)
+* Invoke *ENOURMOUS* functions that draw to screen, manipulate the MCS, clear
+  VRAM, change the Setup parameters, change the on-screen Cursor, print error
+  messages, remap F-key codes, ... (basically everything).
+
+My best intuition so far is that the two jump buffers are for the add-in and
+the main menu, although I'm not sure why there's a need to save state like
+this. I have no intuition yet about the meaning of the 12 states. Though I do
+suspect that the enormous functions I found are related to starting new
+applications, mainly because of %46d which clears the last three eights of the
+RAM, and %846 which clears 1024 bytes of probably-VRAM. Both are called from
+<80089c12> which is called from <8008a42e> which is called from state #2 (and
+does a hell of a lot of MCS-related calls inside its subroutine <80081cea>).
+
+
 <80089d8a GetKeyWait_Dispatcher>
  r4: ??? (return value of setjmp/longmp when called from GetKeyWait_Main)
      appears to be some sort of state (one exists per jump buffer)