[Python-Dev] PEP 287: reStructuredText Standard DocstringFormat

[Samuele Pedroni]

From: David Goodger <goodger@users.sourceforge.net>
> David Abrahams wrote:
> > Is it just me, or are docstrings less-convenient than comments?
> 
> How do you mean?
> 

>From my POV, docstrings want to be short, the problem
being that they are placed inside definitions, they divide
def from code. So the idea of a primary docstring (that
end up in __doc__) and a secondary (only for 
auto-documentating extraction) docstring does not really
solve this.

Comments, naturally put in front of the definition,
do not suffer of this.

If I channel correctly that tradition, Common
Lisp has docstrings too, but long docstrings
are considered bad style.

regards.