Draft: Add comments to allocator code

Having gone through some of this code recently, I thought I'd share my code comments to make things easier on the next person.