[Python-Dev] [Doc-SIG] that library reference, again

[Guido van Rossum]

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