I've written before about why I'm not really fond of docstrings in Python. I continue to feel that way, but at the same time I have to acknowledge that the Python world has made its decision; although help() et al have some heroic hacks to deal with documentation comments, the only fully supported in-Python way to document your module for other people is with docstrings.

This doesn't mean that docstrings are the best way to document your modules. Python's own module documentation, for example for the os module, is much more extensive than what 'help()' on the module will give you. The in-Python version is basically a moderate summary of the full documentation. But writing this sort of documentation is a lot of work, and if you're only going to write documentation for a public module in one place and once, it's clear that it has to be docstrings.

I tend to write docstring based documentation only erratically for non-public code. Documentation in comments simply looks better and 'more right' to me (and I find it less distracting when it's placed before a declaration, instead of between a declaration and the code as a docstring needs to be). I assume that anyone who needs to work with the code is going to have to read it, at which point they're going to see the comments. However this is partly because we don't have a stand-alone collection of Python modules that are reused across disparate programs, which means that I'm basically never in a situation where I just want to know what a module does so I can use it in a new program.

I definitely have mixed feelings about how Python has chosen to explicitly expose docstrings as attributes on functions, classes, and so on. On the one hand, it makes the simple version of help() be pretty straightforward and non-magical; you basically combine dir() and looking at everything's __doc__. On the other hand, that __doc__ is exposed to Python code has tempted me into abusing it for passing around other function-related information that I wanted my code to have access to. And of course the real version of help() is rather more complicated.

(In theory this also decouples where docstrings live from help()'s implementation. For example, Python 3.x could decide to turn properly formatted comments that are right before declarations into docstrings if the declaration didn't itself already have a docstring.)

My aesthetic feelings about how docstrings look are probably significantly cultural, in that most of the programming languages I've used and been exposed to used explicit comments and not docstrings and so I'm not used to them. I don't know if docstrings read more naturally to people who 'grew up' in Python and similar languages, but I suspect that they may well do so. Perhaps I should make an effort to write more docstrings in future Python code, instead of reflexively documenting everything in comments.

(Not that I write much Python code these days. But my most recent Python code was once again all comments and no docstrings, although it's a program and not a module.)