[Python-Dev] should doc string content == documentation content?
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 <wink>, 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