At the risk of sounding snarky, I feel like a block of code comments explaining the naiive approach that was rejected, as well as the particular edge cases that

At the risk of sounding snarky, I feel like a block of code comments explaining the naiive approach that was rejected, as well as the particular edge cases that this is handling which the simpler generalized case doesn't handle, would help a lot for that. I realize that as developers we often glaze over the comments (my editor even shows them as low contrast grey), but docstrings and code comments can be tremendously valuable when trying to understand why something needs to do things a particular way.