[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. _______________________________________________ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
