immunant
Document current relooper algorithm and do minor cleanup
I've gone through the current relooper algorithm and added documentation and comments to clarify what the algorithm is currently doing. The module docs now have an overview of what the algorithm does, and I've added many verbose comments to help understand what each step of the algorithm is doing and why we do the things we do. I've aired on the side of verbosity for many of these comments, trying to capture all of the information I needed to understand the algorithm.
I've also done a small number of cleanup changes in places where the code was doing something unnecessary or was expressed in a way that I found hard to follow. ~~None of the changes should change behavior, expect for the one place where I added a panic! to surface an error case that was previously being silently ignored.~~
Note that this is not meant to be reviewed one commit at a time. Intermediate commits sometimes have incorrect comments that I fix in later commits.
Ah, I see my error case that should never happen has happened. I'll look into that and likely just revert the panic! I added.
A lot of this documentation is now out of date with all of the reworkings to relooper, so I don't think it's worth trying to clean this up to land first. I'll try to remember to address the feedback here as part of the upcoming PR(s) with the relooper changes.