Created on 2013-01-13 15:26 by serhiy.storchaka, last changed 2013-04-14 21:47 by eli.bendersky.
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.").
On Thu, Jan 24, 2013 at 10:02 AM, Ezio Melotti <report@bugs.python.org>wrote:
>
> Ezio Melotti added the comment:
>
>").
>
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
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.