[docs] Add docstrings for ElementTree module (issue 16954)

[merwok at netwok.org]

http://bugs.python.org/review/16954/diff/7390/Lib/xml/etree/ElementTree.py
File Lib/xml/etree/ElementTree.py (right):

http://bugs.python.org/review/16954/diff/7390/Lib/xml/etree/ElementTree.py#newcode1
Lib/xml/etree/ElementTree.py:1: """Lightweight XML support for Python
2.3 and later.
Also “lightweight” is disputed, there was a python-dev thread and a bug
report that lead to the rst docs being edited.

http://bugs.python.org/review/16954/diff/7390/Lib/xml/etree/ElementTree.py#newcode27
Lib/xml/etree/ElementTree.py:27: And a number of child elements stored
in a Python sequence.
When a noun is used as adjective, it’s used in the singular.  “child
elements” is correct.

http://bugs.python.org/review/16954/diff/7390/Lib/xml/etree/ElementTree.py#newcode170
Lib/xml/etree/ElementTree.py:170: """Dictionary of the tag's
attributes."""
s/tag/element/

A tag is the concrete bytes used to mark the beginning and end of an
element.  The thing/concept/object itself, with parent, children and
attributes, is an element.

http://bugs.python.org/review/16954/diff/7390/Lib/xml/etree/ElementTree.py#newcode189
Lib/xml/etree/ElementTree.py:189: def __init__(self, tag, attrib={},
**extra):
Note that __init__ methods are typically documented in the class
docstring.

http://bugs.python.org/review/16954/diff/7390/Lib/xml/etree/ElementTree.py#newcode237
Lib/xml/etree/ElementTree.py:237: """
Magic methods don’t usually have docstrings, because they implement
generic methods or protocols that people know how to use.  If you know
that something is iterable, you don’t look at help(something.__iter__),
you know how to use iter or a for loop.  So to document specific meaning
of an __iter__ or __len__ method, I would put information in the class
docstring.  Does that make sense?

http://bugs.python.org/review/16954/diff/7390/Lib/xml/etree/ElementTree.py#newcode254
Lib/xml/etree/ElementTree.py:254: """
This docstring is valid for all sequence __getitem__ methods :)  I would
just remove it.

http://bugs.python.org/review/16954/diff/7390/Lib/xml/etree/ElementTree.py#newcode295
Lib/xml/etree/ElementTree.py:295: 'elements' is a sequence object with
zero or more elements.
s/sequence object/sequence/

http://bugs.python.org/review/16954/