[Python-Dev] PEP 287: reStructuredText Standard DocstringFormat

Samuele Pedroni pedroni@inf.ethz.ch
Sat, 6 Apr 2002 19:31:25 +0200

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.