Documentation for #991

My bad, I didn't update the documentation in #991 (I was mostly expecting feedback before doing further changes) :)