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

Fred L. Drake, Jr. fdrake at acm.org
Sun Jul 24 17:55:48 CEST 2005

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.

More information about the Python-Dev mailing list