[issue16954] Add docstrings for ElementTree module

Change by Neil Schemenauer : -- resolution: -> fixed stage: needs patch -> resolved status: open -> closed ___ Python tracker ___

[issue16954] Add docstrings for ElementTree module

Chitrank-Dixit 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. --

[issue16954] Add docstrings for ElementTree module

Chitrank-Dixit added the comment: I would like to work on this issue, I found this open and needs a patch. -- nosy: +Chitrank-Dixit ___ Python tracker ___

[issue16954] Add docstrings for ElementTree module

Change by Serhiy Storchaka : -- stage: patch review -> needs patch versions: +Python 3.7, Python 3.8 -Python 3.4 ___ Python tracker ___

[issue16954] Add docstrings for ElementTree module

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 rep...@bugs.python.org http://bugs.python.org/issue16954

[issue16954] Add docstrings for ElementTree module

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 rep...@bugs.python.org http://bugs.python.org/issue16954

[issue16954] Add docstrings for ElementTree module

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 rep...@bugs.python.org http://bugs.python.org/issue16954

[issue16954] Add docstrings for ElementTree module

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

[issue16954] Add docstrings for ElementTree module

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

[issue16954] Add docstrings for ElementTree module

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!) -

[issue16954] Add docstrings for ElementTree module

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

[issue16954] Add docstrings for ElementTree module

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...

[issue16954] Add docstrings for ElementTree module

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

[issue16954] Add docstrings for ElementTree module

Eli Bendersky added the comment: On Thu, Jan 24, 2013 at 10:02 AM, Ezio Melotti rep...@bugs.python.orgwrote: 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

[issue16954] Add docstrings for ElementTree module

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

[issue16954] Add docstrings for ElementTree module

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

[issue16954] Add docstrings for ElementTree module

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. --

[issue16954] Add docstrings for ElementTree module

Changes by Tshepang Lekhonkhobe tshep...@gmail.com: -- nosy: +tshepang ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue16954 ___ ___

[issue16954] Add docstrings for ElementTree module

Changes by Serhiy Storchaka storch...@gmail.com: -- assignee: serhiy.storchaka - docs@python ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue16954 ___

[issue16954] Add docstrings for ElementTree module

Changes by Serhiy Storchaka storch...@gmail.com: -- assignee: docs@python - serhiy.storchaka ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue16954 ___

[issue16954] Add docstrings for ElementTree module

Changes by David Lam d...@dlam.me: -- nosy: +dlam ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue16954 ___ ___ Python-bugs-list mailing list

[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:

[issue16954] Add docstrings for ElementTree module

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

[issue16954] Add docstrings for ElementTree module

Changes by Ezio Melotti ezio.melo...@gmail.com: -- nosy: +ezio.melotti ___ Python tracker rep...@bugs.python.org http://bugs.python.org/issue16954 ___ ___