[Python-Dev] Best practice for documentation for std lib

Stephen J. Turnbull turnbull at sk.tsukuba.ac.jp
Mon Sep 23 07:34:54 CEST 2013

Guido van Rossum writes:
 > On Sun, Sep 22, 2013 at 5:31 PM, Steven D'Aprano <steve at pearwood.info> wrote:

 >> My own preference is to err on the side of too much rather than
 >> too little, since I live by help() and only fall back on the web
 >> documentation when I really must.

 > I guess preferences differ.

Indeed.  Abstractly I agree with Steven: there are some modules such
as statistics where it would be nice for users to have long docstrings
that might even be the full source for the web docs if the module
author so prefers.

But given that Python has an existing policy of concise docstrings
(which indeed is useful when browsing code) and a separate manual, I
withdraw my support for changing practice.  (Sorry, Steven.)

More information about the Python-Dev mailing list