Add lots more documentation

This file now includes copious notes on how the two functions work.
May my peers find them enlightening.