Author MLModel
Recipients MLModel, georg.brandl
Date 2009-07-15.00:55:25
SpamBayes Score 2.2102e-09
Marked as misclassified No
Message-id <1247619329.11.0.425030564778.issue6488@psf.upfronthosting.co.za>
In-reply-to
Content
The documentation of ElementTree mentions "path" in describing the
arguments to certain methods. However, "path" is never defined. I
realize that a "path" is (at least a partial implementation of) an
XPath, but there's nothing in the documentation to suggest that to
someone who is not aware of XPath. I also realize that there is a
reference to the external ElementTree documentation, and that
ElementTree support for XPath is documented there. I think "path" should
at least be clarified with a reference that says something like "As used
here the term 'path' refers to ElementTree's support for the XML Path
Language (XPath); see
see http://effbot.org/zone/element-xpath.htm fordetails"

Next, a swarm of nits:

The documentation of the Element methods find, findall, and findtext say
that their arguments can be a tag name or path. (Using the same wording,
which makes it strange that the argument to findtext is called
"condition" while the argument to the other two methods are called
"match". I'm sure there's something important about this distinction,
but I can't figure it out from the documentation.

The documentation of the corresponding methods of ElementTree call the
arguments "path", rather than "tag" or "condition". The real problem is
that these methods are documented with respect to the element(s) "with
the given tag". [The "the" is missing from the documentation of
ElementTree.find and findall.] The documentation says these methods are
the same as calling the corresponding method on getroot(), but whereas
the Element methods refer to tag name or path, the ElementTree methods,
although they call their arguments "path", only mention tag names.
Finally, the ElementTree methods say "path is the [top-level] element to
look for", which, it seems to me, is redundant given the first sentence
of each of each method's documentation.
History
Date User Action Args
2009-07-15 00:55:29MLModelsetrecipients: + MLModel, georg.brandl
2009-07-15 00:55:29MLModelsetmessageid: <1247619329.11.0.425030564778.issue6488@psf.upfronthosting.co.za>
2009-07-15 00:55:27MLModellinkissue6488 messages
2009-07-15 00:55:26MLModelcreate