[docs] [issue14006] Improve the documentation of xml.etree.ElementTree

[Ezio Melotti]

Ezio Melotti <ezio.melotti at gmail.com> added the comment:

Converting sounds good to me, but it should be done carefully.

I think you can have two paragraphs in the docstrings: the first with the description of what it does and what it returns, and the second with the arguments.

For example Lib/xml/etree/ElementTree.py:355:
# Finds the first matching subelement, by tag name or path.
#
# @param path What element to look for.
# @keyparam namespaces Optional namespace prefix map.
# @return The first matching element, or None if no element was found.
# @defreturn Element or None

can become something like:
"""
Finds the first matching subelement, by tag name or path
and returns the first matching element, or None if no
 element was found.

*path* is the element to look for and *namespace* is an
optional namespace prefix map.
"""

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue14006>
_______________________________________