here's a patch that clarifies some docstrings a bit. Please take a look. I'll push to master if this is OK.

Thanks,

Phil