[Python-Dev] PEP 287: reStructuredText Standard DocstringFormat

[Guido van Rossum]

> 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>

Indeed.  This is how I originally envisioned docstrings, and this is
how I still like to see them: short hints that mean you don't have to
look it up in the manual in most cases (if you have some common sense
and experience and aren't looking for how hairs are split in edge
cases).

> putting the markup for the second in the first would be an abuse.

Agreed.

> 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.

But note that there are other points of view.  I don't mind if some
package author wants to keep all the docs together with the code and
wants to stick it all in the docstrings, and run some tool that
extracts the docs and formats them as a reference manual.  That's just
not how I want to manage the standard library docs.

--Guido van Rossum (home page: http://www.python.org/~guido/)