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

[M.-A. Lemburg]

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 ! ::::