docstrings style question

[Ryan Ginstrom]

> On Behalf Of Steve Brown
> What do you think?

I think that comments are for maintainers, and docstrings are for users. 

Some of the things I use comments for:
* Visually separate classes (using a syntax-highlighting editor)
* Explain algorithm choices
* Explain bug fixes so I don't later "fix" code back to the buggy version

Some of the things I use docstrings for:
* Describe interface (inputs/outputs)
* Sample usage

I personally don't use doctests, but that's one more use of docstrings.

Regards,
Ryan Ginstrom