[issue14006] Improve the documentation of xml.etree.ElementTree

Changes by Eli Bendersky : -- resolution: -> fixed stage: -> committed/rejected status: open -> closed ___ Python tracker ___ ___ Py

[issue14006] Improve the documentation of xml.etree.ElementTree

Changes by Tshepang Lekhonkhobe : -- nosy: +tshepang ___ Python tracker ___ ___ Python-bugs-list mailing list Unsubscribe: http://mai

[issue14006] Improve the documentation of xml.etree.ElementTree

Roundup Robot added the comment: New changeset 78038b6e0a85 by Eli Bendersky in branch 'default': Issue #14006: improve the documentation of xml.etree.ElementTree http://hg.python.org/cpython/rev/78038b6e0a85 -- ___ Python tracker

[issue14006] Improve the documentation of xml.etree.ElementTree

Eli Bendersky added the comment: There are two parallel discussions going on here: 1. The external ReST documentation 2. The internal docstring documentation I opened the issue with (1) in focus, since it's more important IMHO. Not only for the usual reasons (most users don't go into the sour

[issue14006] Improve the documentation of xml.etree.ElementTree

Eli Bendersky added the comment: First step in the right direction - e38f4cf482c7 -- ___ Python tracker ___ ___ Python-bugs-list mail

[issue14006] Improve the documentation of xml.etree.ElementTree

Roundup Robot added the comment: New changeset e38f4cf482c7 by Eli Bendersky in branch 'default': Issue #6488: Explain the XPath support of xml.etree.ElementTree, with code http://hg.python.org/cpython/rev/e38f4cf482c7 -- nosy: +python-dev ___ Python

[issue14006] Improve the documentation of xml.etree.ElementTree

Eli Bendersky added the comment: > BTW, the issue 6488 is still opened. I did not check if there's something > left to do before to close it. The fundamental problem issue #6488 was opened for still exists - the docs use the term "path" without defining it. This should be addressed.

[issue14006] Improve the documentation of xml.etree.ElementTree

Florent Xicluna added the comment: FWIW, Fredrik, who is the creator of ElementTree, had a preference for JavaDoc conventions, as explained here: http://bugs.python.org/issue6488#msg102087 They are compatible with the tool PythonDoc, authored by Fredrik too: http://www.effbot.org/zone/pythondo

[issue14006] Improve the documentation of xml.etree.ElementTree

Leon Matthews added the comment: Thank you Éric and Ezio. I'll produce a patch to convert the javadoc to docstrings this week, then submit it here. -- ___ Python tracker ___ _

[issue14006] Improve the documentation of xml.etree.ElementTree

Éric Araujo added the comment: My general rule is that function/method docstrings are better short descriptions of what the function does and what the arguments are, a usage reminder for people who have already used the function. Classes docstrings can tell a bit more about how the class is

[issue14006] Improve the documentation of xml.etree.ElementTree

Ezio Melotti added the comment: Converting sounds good to me, but it should be done carefully. I think you can have two paragraphs in the docstrings: the first with the description of what it does and what it returns, and the second with the arguments. For example Lib/xml/etree/ElementTree.p

[issue14006] Improve the documentation of xml.etree.ElementTree

Éric Araujo added the comment: > The ElementTree.py module has good JavaDoc-style function-level > documentation, but as it's not > in docstring format, it can't be seen from the interactive help. > > I'd be willing to convert the current comments into docstrings, as long as I > wouldn't be >

[issue14006] Improve the documentation of xml.etree.ElementTree

Leon Matthews added the comment: The ElementTree.py module has good JavaDoc-style function-level documentation, but as it's not in docstring format, it can't be seen from the interactive help. I'd be willing to convert the current comments into docstrings, as long as I wouldn't be stepping on

[issue14006] Improve the documentation of xml.etree.ElementTree

Stefan Behnel added the comment: Oh, and here are the ReST sources of the lxml docs: https://github.com/lxml/lxml/tree/master/doc/ Specifically the tutorial: https://raw.github.com/lxml/lxml/master/doc/tutorial.txt and the parsing part: https://raw.github.com/lxml/lxml/master/doc/parsing.tx

[issue14006] Improve the documentation of xml.etree.ElementTree

Stefan Behnel added the comment: Both lxml and ElementTree have tutorials: http://effbot.org/zone/element.htm http://lxml.de/tutorial.html Here is another tutorial that may server as a source for an intro: http://infohost.nmt.edu/tcc/help/pubs/pylxml/web/index.html And the general ET docume

[issue14006] Improve the documentation of xml.etree.ElementTree

Changes by Arfrever Frehtes Taifersar Arahesis : -- nosy: +Arfrever ___ Python tracker ___ ___ Python-bugs-list mailing list Unsubscri

[issue14006] Improve the documentation of xml.etree.ElementTree

New submission from Eli Bendersky : The documentation of xml.etree.ElementTree has to be improved. The first, very obvious step, would be to start the documentation page with a general overview of the module + some simple examples. The current opening section makes no sense for this module. -