[issue16954] Add docstrings for ElementTree module
New submission from Serhiy Storchaka:
Perhaps almost all Doxygen comments in ElementTree module should be converted to docstrings.
----------
assignee: docs@python
components: Documentation, XML
messages: 179881
nosy: docs@python, eli.bendersky, serhiy.storchaka
priority: normal
severity: normal
stage: needs patch
status: open
title: Add docstrings for ElementTree module
type: enhancement
versions: Python 3.4
_______________________________________
Python tracker
Eli Bendersky added the comment:
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.
----------
keywords: +easy
_______________________________________
Python tracker
Changes by Ezio Melotti
Changes by Serhiy Storchaka
Changes by David Lam
Changes by Serhiy Storchaka
Changes by Tshepang Lekhonkhobe
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").
----------
_______________________________________
Python tracker
Eli Bendersky added the comment:
On Thu, Jan 24, 2013 at 10:02 AM, Ezio Melotti
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?
----------
_______________________________________
Python tracker
Ezio Melotti added the comment:
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.
----------
_______________________________________
Python tracker
David Lam added the comment:
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)
----------
_______________________________________
Python tracker
Ezio Melotti added the comment:
(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.
----------
_______________________________________
Python tracker
David Lam added the comment:
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
----------
keywords: +patch
Added file: http://bugs.python.org/file29095/issue16954.patch
_______________________________________
Python tracker
Ezio Melotti added the comment: 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__?
----------
stage: needs patch -> patch review
_______________________________________
Python tracker
David Lam added the comment: 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.
----------
Added file: http://bugs.python.org/file29278/issue16954-v2.patch
_______________________________________
Python tracker
Eli Bendersky added the comment:
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.
----------
_______________________________________
Python tracker
Roundup Robot added the comment:
New changeset f27d7c1eac4d by Eli Bendersky in branch 'default':
Issue #16954: Add docstrings for ElementTree
http://hg.python.org/cpython/rev/f27d7c1eac4d
----------
nosy: +python-dev
_______________________________________
Python tracker
Eli Bendersky added the comment:
David, would you like to pursue this further (figuring out how to make docstrings show in help() without duplicating?)
----------
_______________________________________
Python tracker
David Lam added the comment:
Hi Eli, I sure would!
(Though, if anyone finds this issue and can figure out a solution, I'd encourage them to post it!)
----------
_______________________________________
Python tracker
Eli Bendersky added the comment:
You can ask on the python-dev mailing list. It's possible that other Python developers ran into a similar issue.
----------
_______________________________________
Python tracker
Change by Serhiy Storchaka
Chitrank-Dixit
Chitrank-Dixit
Change by Neil Schemenauer
participants (8)
-
Chitrank-Dixit -
David Lam
-
Eli Bendersky
-
Ezio Melotti
-
Neil Schemenauer
-
Roundup Robot
-
Serhiy Storchaka
-
Tshepang Lekhonkhobe