On Sun, Sep 22, 2013 at 9:53 AM, Stephen J. Turnbull <step...@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)
_______________________________________________ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com