MAINT: fixes doc bugs, and other comments from @ElBrogrammer