[docs] [issue16954] Add docstrings for ElementTree module

[David Lam]

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