Revisiting this some months later while thinking about programming in general, I realize that that what I want from a nextgen magic development environment are are live comments.
Take this _parseDefinition method, for example, and now compare it to the RSCAssembler's getRR method. The latter has a comment (with an interesting diagram), and the former does not. Suppose even that there were a comment for the _parseDefinition method—it might contain a snippet that's meant to be sample input to help visualize what the method is doing—there would still be the matter of needing to simulate the program in your head. Really, what I want is to be able to write out a snippet and then while reading the code here, anyone can mouse over each statement in the method definition and see what effect it has—say a caret moves along, pointing at the scanner "tip", and visually chunking the tokens.
One should also be able to dynamically modify that snippet—let's say they wanted to "link" the live, scrubbable execution to a particular point in Fig. 1 (the fixT entry instead of fixP, for example)—in this case that snippet should "take over" the live comment, so we can concretely visualize execution of it instead. We should go further than that, even, and not even require the reader know which part of Fig. 1 is actually handled by this section of the code. We should be able to dynamically discover, based on the Ctrl+Space activation, that _parseDefinition is used to handle the fixP, fixD, and fixT lines, and then then reader can point to them (like the difference between a command-line interface where you have to know what you're allowed to do and how to say it, compared to a graphical interface that visually communicates the program's affordances).
The closest I've seen to this are the Moonchild editor :https://harc.github.io/moonchild/ and REPLugger :https://github.com/Glench/REPLugger.
