I agree that commit messages aren't a good place for detailed documentation. Another reason is that if you had a mistaken understanding when you made the commi

I agree that commit messages aren't a good place for detailed documentation. Another reason is that if you had a mistaken understanding when you made the commit and wrote up that understanding in the commit message, you're creating a greater risk of misleading future readers than if you'd put the writeup in a file which can itself be version-controlled. I think the right place isn't necessarily code comments; separate internals documentation (in the same repo as the code) can be good too. Then the comment near the code can just be a cross-reference.