[Python-Dev] PEP 287: reStructuredText Standard DocstringFormat

[Samuele Pedroni]

From: Samuele Pedroni <pedroni@inf.ethz.ch>
>
> If I channel correctly that tradition, Common
> Lisp has docstrings too, but long docstrings
> are considered bad style.
>

My point is not against docstrings,
it is against long primary/secondary docstrings,
and at least IMHO the attitude of Guido
wrt to leaving things as they are for the std
lib seems to rhyme with this.

Here is an example from Common Lisp:

A docstring for the GETHASH function

CL-USER 13 > (documentation 'gethash 'function)
"Finds the entry in Hash-Table whose key is Key and returns the associated
value and T as multiple values, or returns Default and Nil if there is no
such entry."

the full fledged doc of it:
<http://www.xanalys.com/software_tools/reference/HyperSpec/Body/f_gethas.htm#ge
thash>

putting the markup for the second in the first would be an abuse.
The primary/secondary splitting (not possible in CL), does
not change this because *in the code*, they end up in the same
place and count visually anyway as one *long* docstring.

regards.