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

Tim Peters tim.peters at gmail.com
Sun Jul 24 18:37:42 CEST 2005

[Skip]

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 sure there is , but via a different route: tools to extract text from the full documentation, not to burden docstrings with an impossible task. Channeling Guido, docstrings are best when they have a "quick reference card" feel, more memory aid than textbook. That doesn't mean it wouldn't also be nice to have "the textbook" online from pydoc/help too, it means that manuals and docstrings serve different purposes.

...

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 cgi.escape docstring should admit to the optional boolan quote argument. I'm not sure why it uses the highfalutin' "SGML entities" either, when the full docs are content to use the plain-folks "HTML-safe" (if anything, I'd expect the full docs to be anal and the docstring to be "friendly"). But that's criticism of the docstring as a docstring, not criticizing the docstring for, e.g., not mentioning xml.sax.saxutils.quoteattr() too.

More information about the Python-Dev mailing list