[Python-Dev] PEP 287: reStructuredText Standard DocstringFormat (original) (raw)

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.

regards.