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

M.-A. Lemburg mal at egenix.com
Mon Jul 25 00:41:14 CEST 2005

skip at pobox.com wrote:

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?

-1 on bloating the source code with documentation that's easily fetchable from the python.org web-site.

-- Marc-Andre Lemburg eGenix.com

Professional Python Services directly from the Source (#1, Jul 25 2005)

Python/Zope Consulting and Support ... http://www.egenix.com/ mxODBC.Zope.Database.Adapter ... http://zope.egenix.com/ mxODBC, mxDateTime, mxTextTools ... http://python.egenix.com/

::: Try mxODBC.Zope.DA for Windows,Linux,Solaris,FreeBSD for free ! ::::

More information about the Python-Dev mailing list