DOC: @wasade's suggestion
DOC: more docstrings, and a few improvements