Reword some comments and docstrings to make them clearer.
Merge pull request #46 from whiteroses/fix.improve-docstrings-and-comments

Reword some comments and docstrings to make them clearer.