should doc string content == documentation content?
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 inclined to think that while it might be a noble goal, it's probably not worth the effort for several reasons. 1. Many objects don't lend themselves to inline documentation. This includes all the basic data types (strings, numbers, lists, tuples, dicts). It could be achieved perhaps by some sort of hackery (e.g., for object foo present the contents of _foo__doc__ if it was a string or unicode object), but that would only be a convention. 2. There's so much more to the documentation than documenting individual objects. 3. When asking pydoc (or help()) to present a module's documentation, it displays a URL for the full module documentation. 4. It would be a *ton* of work. 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? Skip
On Sunday 24 July 2005 09:34, skip@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. <fdrake at acm.org>
On 7/24/05, Fred L. Drake, Jr.
On Sunday 24 July 2005 09:34, skip@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.
This ties well with the discussion on Doc-SIG a few months ago about manual docs vs. in-code docs. If a system could be devised to "pull" the docstrings into the manual (at appropriate places), the issue of syncing the docs partially goes away. cheers,
On Sunday 24 July 2005 19:24, Martin Blais wrote:
This ties well with the discussion on Doc-SIG a few months ago about manual docs vs. in-code docs. If a system could be devised to "pull" the docstrings into the manual (at appropriate places), the issue of syncing the docs partially goes away.
Yes, it does. Avoiding the maintenance burden is a matter of having only one source for the docs, and doesn't not inform the selection of which place is best in a substantial way. A little though. -Fred -- Fred L. Drake, Jr. <fdrake at acm.org>
Fred L. Drake, Jr. wrote:
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.
Maybe docstrings should be kept in a separate part of the .pyc file, and not loaded into memory until requested? -- Greg Ewing, Computer Science Dept, +--------------------------------------+ University of Canterbury, | A citizen of NewZealandCorp, a | Christchurch, New Zealand | wholly-owned subsidiary of USA Inc. | greg.ewing@canterbury.ac.nz +--------------------------------------+
[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.
On 7/24/05, Tim Peters
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 agree that docstrings shouldn't be a deep copy of _Python in a
Nutshell_, there are definitely some areas of the standard library
that could use some help. threading comes to mind immediately.
--
Tim Lesher
[Tim Lesher]
While I agree that docstrings shouldn't be a deep copy of _Python in a Nutshell_, there are definitely some areas of the standard library that could use some help. threading comes to mind immediately.
Sure! The way to cure that one is to write better docstrings for threading -- go for it.
skip@pobox.com wrote:
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 inclined to think that while it might be a noble goal, it's probably not worth the effort for several reasons.
1. Many objects don't lend themselves to inline documentation. This includes all the basic data types (strings, numbers, lists, tuples, dicts). It could be achieved perhaps by some sort of hackery (e.g., for object foo present the contents of _foo__doc__ if it was a string or unicode object), but that would only be a convention.
2. There's so much more to the documentation than documenting individual objects.
3. When asking pydoc (or help()) to present a module's documentation, it displays a URL for the full module documentation.
4. It would be a *ton* of work.
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?
-1 on bloating the source code with documentation that's easily fetchable from the python.org web-site. -- Marc-Andre Lemburg eGenix.com Professional Python Services directly from the Source (#1, Jul 25 2005)
Python/Zope Consulting and Support ... http://www.egenix.com/ mxODBC.Zope.Database.Adapter ... http://zope.egenix.com/ mxODBC, mxDateTime, mxTextTools ... http://python.egenix.com/
::: Try mxODBC.Zope.DA for Windows,Linux,Solaris,FreeBSD for free ! ::::
participants (7)
-
Fred L. Drake, Jr. -
Greg Ewing -
M.-A. Lemburg -
Martin Blais -
skip＠pobox.com -
Tim Lesher -
Tim Peters