DOC: added more meat in the docstrings