New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Improve the documentation of xml.etree.ElementTree #58214
Comments
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. |
Both lxml and ElementTree have tutorials: http://effbot.org/zone/element.htm 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. |
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: |
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? |
|
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: # @param path What element to look for. can become something like: *path* is the element to look for and *namespace* is an |
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). |
Thank you Éric and Ezio. I'll produce a patch to convert the javadoc to docstrings this week, then submit it here. |
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: However, I agree it makes sense to turn them into docstrings if the package is only maintained in the standard library. BTW, the bpo-6488 is still opened. I did not check if there's something left to do before to close it. |
The fundamental problem issue bpo-6488 was opened for still exists - the docs use the term "path" without defining it. This should be addressed. |
New changeset e38f4cf482c7 by Eli Bendersky in branch 'default': |
First step in the right direction - e38f4cf482c7 |
There are two parallel discussions going on here:
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 source to find docstrings), but also because ElementTree.py is just a "reference implementation" in 3.3, since the _elementtree extension is imported by default and is expected to be used on the vast majority of platforms. Therefore, it's important to have external documentation serving essentially as an API spec implemented once in Python and once in C. Not that I would object to docstring patches. But it doesn't appear Leon's work is progressing. In any case, I'll be focusing on the ReST docs. |
New changeset 78038b6e0a85 by Eli Bendersky in branch 'default': |
Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.
Show more details
GitHub fields:
bugs.python.org fields:
The text was updated successfully, but these errors were encountered: