[Python-Dev] should doc string content == documentation content? (original) (raw)

skip@pobox.com skip at pobox.com
Sun Jul 24 15:34:59 CEST 2005

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

More information about the Python-Dev mailing list