fix doc and clean comments, re #8990