DOC: more docstring notes and parameter descriptions