documentation fixes for refactoring induced mess, some stylistic touchups