[Python-Dev] [Doc-SIG] that library reference, again (original) (raw)

Guido van Rossum guido at python.org
Mon Jan 30 23🔞25 CET 2006

On 1/26/06, Robey Pointer <robey at lag.net> wrote: [quoting /F]

> moving all of (or parts of) the reference documentation in to the > library source code would be an alternative, of course [1], but that > would basically mean starting over from scratch.

Bad idea. Putting the full docs in the source adds more coupling between the files and makes it harder instead of easier to edit the docs, especially for C code. Also, the needs for interactive help are different from those for off-line docs.

Also note that several object types (e.g. lists and dicts, like used for sys.path and sys.modules) don't have doc properties so documenting them in the source is problematic.

The list goes on; e.g. the source code ordering may not be the same as the ideal documentation ordering; where do you put subsection introductions, etc.

I think that would be a good thing to do no matter what markup is used. It always irritates me when I do 'help(sys.something)' and get one line of ASCII art that's probably useful to the module author but nobody else.

Wrong guess. That string was put there by the author specifically so that it shows up in help(sys.whatever), and the author probably (mistakenly) though that whatever he wrote was sufficient. If you ever find a docstring that is IYO insufficient, please submit a patch or bug. Until we have a better mechanism, simply submitting the new text of the docstring, without bothering to make it into a context-diff or to use the proper markup, is fine.

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

More information about the Python-Dev mailing list