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

[Fred L. Drake, Jr.]

On Sunday 24 July 2005 09:34, skip at pobox.com wrote:
 > 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.

All your reasons not to include all the documentation in the docstrings are 
good.  I'll add:

    5. It would be a maintenance problem keeping the two sets of docs in sync.

    6. Most Python processes don't need the docs anyway.  I suspect the
       docstrings are used primarily in the interactive interpreter and other
       development tools.  Zope 2 is the only application that uses
       docstrings at runtime that I'm aware of.  Given that Zope 3 abandons
       this, I'm not inclined to take that as a guiding example.

 > 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?

The low-hanging fruit, of course, is to close the report with a 'reject' 
status.


  -Fred

-- 
Fred L. Drake, Jr.   <fdrake at acm.org>