[Python-Dev] should doc string content == documentation content?

[skip@pobox.com]

There's a new bug report on SF (#1243553) complaining (that's probably not
the right word) that the documentation for cgi.escape available from pydoc
isn't as detailed as that in the full documentation.  Is there any desire to
make the runtime documentation available via pydoc or help() as detailed as
the full documentation?  I'm inclined to think that while it might be a
noble goal, it's probably not worth the effort for several reasons.

    1. Many objects don't lend themselves to inline documentation.  This
       includes all the basic data types (strings, numbers, lists, tuples,
       dicts).  It could be achieved perhaps by some sort of hackery (e.g.,
       for object foo present the contents of _foo__doc__ if it was a string
       or unicode object), but that would only be a convention.

    2. There's so much more to the documentation than documenting individual
       objects.

    3. When asking pydoc (or help()) to present a module's documentation, it
       displays a URL for the full module documentation.

    4. It would be a *ton* of work.

While I can fix the isolated case of cgi.escape fairly easily, I'm not
inclined to.  (I will gladly do it if the sentiment is that picking off such
low-hanging fruit is worthwhile.)  What do other people think?

Skip