[Python-Dev] Best practice for documentation for std lib
Guido van Rossum
guido at python.org
Sun Sep 22 19:07:28 CEST 2013
On Sun, Sep 22, 2013 at 9:53 AM, Stephen J. Turnbull <stephen at xemacs.org>wrote:
> Eli Bendersky writes:
> > IMHO the right way to think about it is that the .rst files are by
> > far the more important documentation. Sometimes we forget that
> > most Python programmers are people who won't go into the source
> Why "source"? The whole point of docstrings is that they are *not*
> comments found only in the source, but available at run time. In fact,
> programmers who also use environments like Lisp or R (not to forget
> Idle) will reach for "help(mean)", and that works fine for Steven,
> because he provides such nice docstrings.
> Some people prefer to write separate manuals, and some modules
> *should* be documented that way because their internal complexity or
> whatever. That's true, but I would hope authors who prefer "literate
> programming" (or the poor man's lit prog that is writing only
> docstrings) are encouraged to do so when appropriate.
> Of course, like any other contribution, since that style is *not*
> currently supported by python-dev, they'd be asked to step up and
> support it themselves -- if a user reports the docs won't build, they
> need to address that like they would a build bug in the code.
Authors writing 3rd party packages can do what they want.
But for the stdlib it's been settled for ages: docstrings should be concise
(but not cryptic(*)), longer documentation go into the separately written
text for docs.python.org.
(*) This is too concise to my taste:
$ ls -?
ls: illegal option -- ?
usage: ls [-ABCFGHLOPRSTUWabcdefghiklmnopqrstuwx1] [file ...]
--Guido van Rossum (python.org/~guido)
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the Python-Dev