[Python-Dev] 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 ___ 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
Re: [Python-Dev] should doc string content == documentation content?
On Sunday 24 July 2005 09:34, [EMAIL PROTECTED] 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 ___ 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
Re: [Python-Dev] should doc string content == documentation content?
[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
Re: [Python-Dev] should doc string content == documentation content?
On 7/24/05, Tim Peters [EMAIL PROTECTED] wrote: 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 [EMAIL PROTECTED] ___ 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
Re: [Python-Dev] should doc string content == documentation content?
[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. ___ 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
Re: [Python-Dev] zlib 1.2.3 is just out
Raymond Hettinger wrote: I'd guess this belongs in 2.5, with a possible retrofit for 2.4. +1 on backporting, but that is up to Anthony. Correct me if I'm wrong - but there isn't much porting to this. AFAICT, this is only relevant for the Windows build (i.e. which version is used in the binaries). For the source distribution, there should be no change (except for PCbuild/readme.txt, which should reflect the version that is used in the Windows build). FWIW, this currently talks about 1.2.1. Regards, Martin ___ 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
Re: [Python-Dev] should doc string content == documentation content?
On 7/24/05, Fred L. Drake, Jr. [EMAIL PROTECTED] wrote: On Sunday 24 July 2005 09:34, [EMAIL PROTECTED] 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, ___ 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
Re: [Python-Dev] should doc string content == documentation content?
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. | [EMAIL PROTECTED] +--+ ___ 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
