homepage

Perhaps almost all Doxygen comments in ElementTree module should be converted to docstrings.

Definitely. And this is one of those issues where I can wholeheartedly say that patches are welcome :-)
Even incremental patching will be OK (i.e. patches documenting single methods or groups of methods).
Incidentally, while replacing the comment by docstring for issue #14377, I noticed an argument (default_namespace) that wasn't documented anywhere, including the ReST docs. So such a transition can have more benefits than seems on the surface.

I would suggest to adapt the comments to follow PEP 257, and in particular:
"""
The docstring is a phrase ending in a period. It prescribes the function or method's effect as a command ("Do this", "Return that"), not as a description; e.g. don't write "Returns the pathname ...".
"""
Currently there are two docstrings, one for write() and one for iterparse() (recently added in #9708). Only the former uses the correct form ("Return" instead of "Returns").

On Thu, Jan 24, 2013 at 10:02 AM, Ezio Melotti <report@bugs.python.org>wrote:
>
> Ezio Melotti added the comment:
>
> I would suggest to adapt the comments to follow PEP 257, and in particular:
> """
> The docstring is a phrase ending in a period. It prescribes the function
> or method's effect as a command ("Do this", "Return that"), not as a
> description; e.g. don't write "Returns the pathname ...".
> """
>
> Currently there are two docstrings, one for write() and one for
> iterparse() (recently added in #9708). Only the former uses the correct
> form ("Return" instead of "Returns").
>
Actually, the latter was copy-pasted from the ReST docs of the method. Does
that PEP 257 suggestion apply to ReST docs as well, or do we have a
discrepancy?

The docs should use "return" too, even though I'm not sure this is enforced. Consistency within the doc page is more important, but I don't think that consistency between comments and docstrings in the code or between docstrings and documentation is so important.

I had an innocent question about the format to use when listing function arguments in docstrings. In the PEP 257 doc, there's a single example:
 def complex(real=0.0, imag=0.0):
 """Form a complex number.
 Keyword arguments:
 real -- the real part (default 0.0)
 imag -- the imaginary part (default 0.0)
I went digging through Lib/ for a good example to follow, but felt a little unsure because the exact format seemed to differ ever so slightly sometimes.
Like in ipaddress.py, a colon is used instead of two hyphens, and it's indented:
 def ip_address(address):
 """Take an IP string/int and return an object of the correct type.
 Args:
 address: A string or integer, the IP address. Either IPv4 or
 IPv6 addresses may be supplied; integers less than 2**32 will
 be considered to be IPv4 by default.
Is there an "ideal" example in the source to try to copy? 
(or maybe this is just a use-your-common-sense thing)

> (or maybe this is just a use-your-common-sense thing)
That's probably the best thing. I don't think we follow any specific convention for args in the docstring. Mostly they are just described in the text, without having lists of args.

Here's a patch which converts all the Doxygen comments in ElementTree.py to docstrings!
Something I noticed was that the 
 from _elementtree import *
...at the bottom of ElementTree.py sort of overwrites the docstrings of the Python module. So if you did... `from xml.etree import ElementTree; help(ElementTree)` from the interpreter, you'll see blank spots for a bunch of classes/methods like Element, ParseError, SubElement etc etc
maybe docstrings should be also added in Modules/_elementtree.c? perhaps that would be too much copy and pastage, hmmm

I left a few comments on rietveld.
In the rst docs the markup used for arguments is *arg*, and this is sometimes reflected in docstrings too. We might want to do this here too, instead of using 'arg' (using 'attr' for attributes it's fine though).
> maybe docstrings should be also added in Modules/_elementtree.c?
Maybe we could have a loop that does something like cfunc.__doc__ = pyfunc.__doc__?

here's an updated patch incorporating the feedback from Ezio and Eric:
 - moved docstrings put in some __special__ method names
 - made the description of 'tag' consistent: 'tag' means the elements name (as opposed to 'tag' being a synonym for "element"!)
 - docstring args now *stared* as opposed to 'quoted'
I also gave a shot at copying the existing docstrings into their respective C counterparts. But it *seems* like you can't do so
that easily for a C extension. Maybe I missed something though: 
>>> from _elementtree import Element as cElement
>>> cElement.__doc__ = 'foobarbaz'
Traceback (most recent call last):
 File "<stdin>", line 1, in <module>
TypeError: can't set attributes of built-in/extension type 'xml.etree.ElementTree.Element'
I see one example in Modules/_json.c where the docstrings were sorta copied and pasted over, so perhaps it's an ok thing to do.

Thanks David, the patch looks good. I will commit it with some slight modifications and touch-ups shortly.
The issue of C extension docstrings vs. Python docstrings is an interesting one. It's a shame that help() shows empty strings, and it's a shame to copy-paste. What do other modules do? It may also be worth asking in python-dev or the docs mailing list and hear suggestions from other developers.

New changeset f27d7c1eac4d by Eli Bendersky in branch 'default':
Issue #16954: Add docstrings for ElementTree
http://hg.python.org/cpython/rev/f27d7c1eac4d 

David, would you like to pursue this further (figuring out how to make docstrings show in help() without duplicating?)

Hi Eli, I sure would!
(Though, if anyone finds this issue and can figure out a solution, I'd encourage them to post it!)

You can ask on the python-dev mailing list. It's possible that other Python developers ran into a similar issue.

I would like to work on this issue, I found this open and needs a patch.

I think the current ticket should be closed as there are no doxygen comments left to convert to docstrings. So I think this issue can be closed.
There are places where there is no docstrings for those we can create a new ticket.