[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 <report@bugs.python.org> <http://bugs.python.org/issue16954> _______________________________________
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 <report@bugs.python.org> <http://bugs.python.org/issue16954> _______________________________________
Changes by Ezio Melotti <ezio.melotti@gmail.com>: ---------- nosy: +ezio.melotti _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16954> _______________________________________
Changes by Serhiy Storchaka <storchaka@gmail.com>: ---------- assignee: docs@python -> serhiy.storchaka _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16954> _______________________________________
Changes by David Lam <d@dlam.me>: ---------- nosy: +dlam _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16954> _______________________________________
Changes by Serhiy Storchaka <storchaka@gmail.com>: ---------- assignee: serhiy.storchaka -> docs@python _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16954> _______________________________________
Changes by Tshepang Lekhonkhobe <tshepang@gmail.com>: ---------- nosy: +tshepang _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16954> _______________________________________
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 <report@bugs.python.org> <http://bugs.python.org/issue16954> _______________________________________
Eli Bendersky added the comment: 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? ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16954> _______________________________________
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 <report@bugs.python.org> <http://bugs.python.org/issue16954> _______________________________________
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 <report@bugs.python.org> <http://bugs.python.org/issue16954> _______________________________________
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 <report@bugs.python.org> <http://bugs.python.org/issue16954> _______________________________________
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 <report@bugs.python.org> <http://bugs.python.org/issue16954> _______________________________________
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 <report@bugs.python.org> <http://bugs.python.org/issue16954> _______________________________________
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 <report@bugs.python.org> <http://bugs.python.org/issue16954> _______________________________________
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 <report@bugs.python.org> <http://bugs.python.org/issue16954> _______________________________________
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 <report@bugs.python.org> <http://bugs.python.org/issue16954> _______________________________________
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 <report@bugs.python.org> <http://bugs.python.org/issue16954> _______________________________________
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 <report@bugs.python.org> <http://bugs.python.org/issue16954> _______________________________________
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 <report@bugs.python.org> <http://bugs.python.org/issue16954> _______________________________________
Change by Serhiy Storchaka <storchaka+cpython@gmail.com>: ---------- stage: patch review -> needs patch versions: +Python 3.7, Python 3.8 -Python 3.4 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue16954> _______________________________________
Chitrank-Dixit <chitrankdixit@gmail.com> added the comment: I would like to work on this issue, I found this open and needs a patch. ---------- nosy: +Chitrank-Dixit _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue16954> _______________________________________
Chitrank-Dixit <chitrankdixit@gmail.com> added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue16954> _______________________________________
Change by Neil Schemenauer <nas-python@arctrix.com>: ---------- resolution: -> fixed stage: needs patch -> resolved status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue16954> _______________________________________
participants (8)
-
Chitrank-Dixit -
David Lam
-
Eli Bendersky
-
Ezio Melotti
-
Neil Schemenauer
-
Roundup Robot
-
Serhiy Storchaka
-
Tshepang Lekhonkhobe