Queue module and Python Documentation Rant

[Skip Montanaro]

    Peter> Roger Binns wrote:
    >> Unfortunately I don't see what you could have done to spot the
    >> following page other than looking at the bottom.  

    Peter> Reading the docs more often would help.  There are many different
    Peter> pages that have such subsection links at the bottom, so one
    Peter> should be used to it.

It's perhaps worth noting that there are basically two types of module doc
structures.  Let's call them the Fred way (such as the docs for the Queue
module) and the Greg way (such as the docs for the optparse module).

There's nothing wrong with the way Greg wrote his docs, but they seem much
less like reference material to me and more like a normal user's manual,
emphasizing the important stuff but without being 100% comprehensive.  That
makes it more challenging than I think it ought to be to answer a simple
question like, "what methods do OptionParser objects implement?"  You can
fall back to pydoc but that requires that most/all methods have doc strings
to be useful.  I have a particularly hard time finding information in the
distutils section of the libref manual.  I should probably pay more
attention to the various submodule docs.

Skip