[issue6489] Documentation of ElementTree.Element.getiterator implies element will always be included

[Mitchell Model]

New submission from Mitchell Model <mlm at acm.org>:

Documentation of ElementTree.Element.getiterator implies element will
always be included, but it is only included if it matches. (It says
"creates a tree iterator with the current element as the root" and also
says, ambiguously, "iterates over this element and all the elements
below it that match the given tag".)

I also feel that it is unclear to leave the term "match" undescribed.
Especially with '*' explicitly mentioned as a possibility, it looks like
one could specify, say, 'Thing*' and get all elements whose tag names
begin with 'Thing', which does not appear to be the case. Also, using
the term "match" is confusing if one understands the term to mean match
an XPath, as (implicitly) used elsewhere in the document, unless match
also means an XPath here too, which I don't think it does. I think
"match" should be reserved for XPath matching in this documentation, and
"equals" for when that is the actual test performed, such as, I think,
in getiterator.

----------
assignee: georg.brandl
components: Documentation
messages: 90529
nosy: MLModel, georg.brandl
severity: normal
status: open
title: Documentation of ElementTree.Element.getiterator implies element will always be included
versions: Python 2.7, Python 3.0, Python 3.1, Python 3.2

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