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

[Tim Peters]

[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.