DOC: @adamrp's comments, and expanded notes/returns
MAINT: removed extraneous sorted