Login | Register For Free | Help
Search for: (Advanced)

Mailing List Archive: Python: Bugs

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

 

 

Python bugs RSS feed   Index | Next | Previous | View Threaded


report at bugs

Feb 13, 2012, 7:28 PM

Post #1 of 11 (188 views)
Permalink
[issue14006] Improve the documentation of xml.etree.ElementTree

New submission from Eli Bendersky <eliben [at] gmail>:

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.

----------
assignee: docs [at] pytho
components: Documentation
keywords: easy
messages: 153318
nosy: docs [at] pytho, eli.bendersky, eric.araujo, ezio.melotti, flox, scoder
priority: normal
severity: normal
status: open
title: Improve the documentation of xml.etree.ElementTree
type: enhancement
versions: Python 3.3

_______________________________________
Python tracker <report [at] bugs>
<http://bugs.python.org/issue14006>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/list-python-bugs%40lists.gossamer-threads.com


report at bugs

Feb 14, 2012, 2:49 AM

Post #2 of 11 (182 views)
Permalink
[issue14006] Improve the documentation of xml.etree.ElementTree [In reply to]

Changes by Arfrever Frehtes Taifersar Arahesis <Arfrever.FTA [at] GMail>:


----------
nosy: +Arfrever

_______________________________________
Python tracker <report [at] bugs>
<http://bugs.python.org/issue14006>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/list-python-bugs%40lists.gossamer-threads.com


report at bugs

Feb 14, 2012, 3:00 AM

Post #3 of 11 (180 views)
Permalink
[issue14006] Improve the documentation of xml.etree.ElementTree [In reply to]

Stefan Behnel <scoder [at] users> 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 documentation is here:

http://effbot.org/zone/element-index.htm#documentation

In terms of licensing, I can't speak for any of the other sources, but as for the lxml documentation, feel free to copy any ET related parts of it that you see fit.

I think the lxml tutorial is gentle enough even for beginners to follow. Note, however, that it uses lxml specific APIs in some places. In the specific case of XPath, the examples should be easily replaced with ElementPath, though.

----------

_______________________________________
Python tracker <report [at] bugs>
<http://bugs.python.org/issue14006>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/list-python-bugs%40lists.gossamer-threads.com


report at bugs

Feb 14, 2012, 3:03 AM

Post #4 of 11 (179 views)
Permalink
[issue14006] Improve the documentation of xml.etree.ElementTree [In reply to]

Stefan Behnel <scoder [at] users> 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.txt

----------

_______________________________________
Python tracker <report [at] bugs>
<http://bugs.python.org/issue14006>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/list-python-bugs%40lists.gossamer-threads.com


report at bugs

Feb 21, 2012, 12:33 PM

Post #5 of 11 (168 views)
Permalink
[issue14006] Improve the documentation of xml.etree.ElementTree [In reply to]

Leon Matthews <leon [at] lost> 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 anybody's toes, and somebody could give me some guidance as to how to convert the @return and @param declarations, and how to handle the C version of the module.

Any volunteers?

----------
nosy: +leonov

_______________________________________
Python tracker <report [at] bugs>
<http://bugs.python.org/issue14006>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/list-python-bugs%40lists.gossamer-threads.com


report at bugs

Feb 22, 2012, 5:27 PM

Post #6 of 11 (168 views)
Permalink
[issue14006] Improve the documentation of xml.etree.ElementTree [In reply to]

Éric Araujo <merwok [at] netwok> 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 anybody's toes,
Great, thanks! I don’t know if the best approach here is to add lengthy docstrings or move the information from the comments into the reST docs. Maybe this should be asked on the core-mentorship or python-dev mailing list.

> and somebody could give me some guidance as to how to convert the @return and @param declarations
In docstrings as well as in reST docs we just use English, with asterisks to mark up parameters, e.g. “*path* is an instance of :class:`ElementPath`. ... Returns ``True`` if there is a match, ``False`` otherwise.”

> and how to handle the C version of the module.
Doctrings for C modules are not hard to find, just a little painful to write. If we agree to turn comments into docstrings and you need help, I’ll be glad to guide you with that.

----------

_______________________________________
Python tracker <report [at] bugs>
<http://bugs.python.org/issue14006>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/list-python-bugs%40lists.gossamer-threads.com


report at bugs

Feb 22, 2012, 7:36 PM

Post #7 of 11 (174 views)
Permalink
[issue14006] Improve the documentation of xml.etree.ElementTree [In reply to]

Ezio Melotti <ezio.melotti [at] gmail> 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.py:355:
# Finds the first matching subelement, by tag name or path.
#
# @param path What element to look for.
# @keyparam namespaces Optional namespace prefix map.
# @return The first matching element, or None if no element was found.
# @defreturn Element or None

can become something like:
"""
Finds the first matching subelement, by tag name or path
and returns the first matching element, or None if no
element was found.

*path* is the element to look for and *namespace* is an
optional namespace prefix map.
"""

----------

_______________________________________
Python tracker <report [at] bugs>
<http://bugs.python.org/issue14006>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/list-python-bugs%40lists.gossamer-threads.com


report at bugs

Feb 22, 2012, 7:47 PM

Post #8 of 11 (169 views)
Permalink
[issue14006] Improve the documentation of xml.etree.ElementTree [In reply to]

Éric Araujo <merwok [at] netwok> 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 supposed to be used, e.g. what particular responsibility they have and what they work with. Module docstrings should help you make sense of the public objects in the module, for example tell about the main classes and functions and briefly mentioning the less important ones.

This is a personal viewpoint; some people use dir and pydoc a lot to get the most info out of a new module, whereas I like separate documentation more.

ElementTree has no docstrings at all, which is IMO bad; I’d like the javadoc comments to be turned into docstrings, and if they are too big they can be reduced to their core and the extra help moved to reST docs (which are at this moment in what looks like a good shape: they have the same info as the javadoc comments from a quick glance).

I think some of the comments can just be deleted, like the @see lines. Finally, a note about the comments for attributes: they should be documented in the reST docs, and for the Python code you have two possibilities: you can document them in the class docstring, or put string literals after them (see http://www.python.org/dev/peps/pep-0258/#attribute-docstrings – they are discarded by Python, so not available to help/pydoc, but some tools can process them).

----------

_______________________________________
Python tracker <report [at] bugs>
<http://bugs.python.org/issue14006>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/list-python-bugs%40lists.gossamer-threads.com


report at bugs

Feb 26, 2012, 12:53 PM

Post #9 of 11 (168 views)
Permalink
[issue14006] Improve the documentation of xml.etree.ElementTree [In reply to]

Leon Matthews <python [at] lost> 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 <report [at] bugs>
<http://bugs.python.org/issue14006>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/list-python-bugs%40lists.gossamer-threads.com


report at bugs

Feb 26, 2012, 2:39 PM

Post #10 of 11 (166 views)
Permalink
[issue14006] Improve the documentation of xml.etree.ElementTree [In reply to]

Florent Xicluna <florent.xicluna [at] gmail> 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/pythondoc.htm


However, I agree it makes sense to turn them into docstrings if the package is only maintained in the standard library.


BTW, the issue 6488 is still opened. I did not check if there's something left to do before to close it.
There's also a patch attached to issue 2864, which need some review.

----------
dependencies: +ElementTree documentation refers to "path" with no explanation, and inconsistently
nosy: +effbot

_______________________________________
Python tracker <report [at] bugs>
<http://bugs.python.org/issue14006>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/list-python-bugs%40lists.gossamer-threads.com


report at bugs

Mar 6, 2012, 5:22 AM

Post #11 of 11 (156 views)
Permalink
[issue14006] Improve the documentation of xml.etree.ElementTree [In reply to]

Eli Bendersky <eliben [at] gmail> 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.

----------

_______________________________________
Python tracker <report [at] bugs>
<http://bugs.python.org/issue14006>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/list-python-bugs%40lists.gossamer-threads.com

Python bugs RSS feed   Index | Next | Previous | View Threaded
 
 


Interested in having your list archived? Contact Gossamer Threads
 
  Web Applications & Managed Hosting Powered by Gossamer Threads Inc.