>> Did my suggestion to alter pydoc output so it always contains a link
    >> to the enclosing module's documentation not seem like a reasonable
    >> compromise?

    Catherine> I actually don't understand how that would help.  The ``pydoc
    Catherine> time`` output doesn't include any information about the
    Catherine> formatting codes (at least, on my system).

No, but it does include a link to the full documentation for the time
module, so should you need more than is in the docstring, in theory
everything you might want would only be one or two clicks away.

    Catherine> Also, ``pydoc`` isn't available on Windows systems, is it?
    Catherine> It isn't on mine; is that a quirk of my setup?

You can fire up a documentation server using

    python -m pydoc -g

which starts an HTTP server available to dispense documentation for
everything in your PYTHONPATH.  You can search for "strftime" there, and
after a fairly long pause it will present you with a link you can click to
get the time module docs.  (I think there is a bug in the way it handles
errors during import of the various modules.)

Alternatively, click the "open browser" button and you will be directed to
the front page of the content it serves.  The resulting user interface is
fairly crude, but if you search for "time" (it's in the lib-dynload section)
and click the link provided, it pops up the pydoc documentation for the time
module.  From there you can click the Module Docs link in the upper
right-hand corner to be taken to the full documentation for the time module.

    Catherine> Yes, certainly, in one place - but isn't it logical for the
    Catherine> docstring to be that one place?

I think most people would argue, "no".  Docstrings are helpers.  The library
reference manual is supposed to be comprehensive.

    Catherine> Here's where I would suggest drawing the line: if the method
    Catherine> is unusable without the information, and it's not easy to
    Catherine> guess or remember, and it's relatively concise, it should be
    Catherine> in the docstring.

This would be a pretty radical change to the documentation.  You're asking
that either

    * Docstrings become the comprehensive source of information instead of
      the library reference manual, or

    * A fair amount of information be duplicated between the library
      reference manual and the docstrings.

I suggest this discussion be moved to the doc-sig@python.org mailing list.
Those are the people who would be best equipped to discuss the overall
topic.  I'm just a single user with my personal perspective on the topic.
I'm not the guy who makes these decisions.

Skip