classification
Title: ElementTree documentation refers to "path" with no explanation, and inconsistently
Type: behavior Stage: resolved
Components: Documentation, XML Versions: Python 3.1, Python 3.2, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: Nosy List: MLModel, effbot, eli.bendersky, eric.araujo, flox, georg.brandl, guettli, jaraco, littlemog, mbone, python-dev, r.david.murray
Priority: low Keywords:

Created on 2009-07-15 00:55 by MLModel, last changed 2012-03-26 18:46 by eli.bendersky. This issue is now closed.

Messages (10)
msg90528 - (view) Author: Mitchell Model (MLModel) Date: 2009-07-15 00:55
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.
msg101868 - (view) Author: Jason R. Coombs (jaraco) * (Python committer) Date: 2010-03-28 17:16
I agree. I found the documentation very difficult to understand.  The term "top-level" can be confusing. Consider instead something like "search the entire tree".

A few other comments about the documentation of findtext:

findtext(path[, default])
    ... Returns the text content of the first matching element, or the default value no element was found...

The first comma (,) following 'element' is unnecessary and in fact incorrect. Also, 'if' is missing. Sentence should read "Returns the text content of the first matching element or the default value if no element was found."

findtext(path[, default])
    ... Note that if the element has is found, but has no text content, this method returns an empty string.

Again, an unnecessary comma exist and there's an extra word. Should read, "Note that if the element is found but has no text content, this method returns an empty string."

Note, the wording changes should be made. The other suggestions should be considered soft suggestions and merely my preference.
msg101869 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2010-03-28 17:26
As per PEP 257, “Returns” should become “Return” (it’s a command, not a description).
msg101875 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2010-03-28 22:14
I think you are incorrect about the comma after element.  Without the comma 'the first matching element or the default value' are tightly bound, meaning that if either of those is true, then the default value is returned.  That's obviously incorrect, so a human will parse the sentence the way you expect.  But I think technically the comma after element turns the sentence into two independent clauses conjoined by 'or', so that either the first matching element is returned, or the default is returned (if no element was found).  I think it also reads better rhythmically (you will note that I used a comma in my sentence, as well, even though in that case no technical ambiguity results from leaving it out).

The comma in the other sentence I think is optional, and I agree that it reads better without it.
msg102087 - (view) Author: Fredrik Lundh (effbot) * (Python committer) Date: 2010-04-01 12:02
> As per PEP 257, “Returns” should become “Return” (it’s a command, not a description).

Upstream ET uses JavaDoc conventions, where the conventions are
designed by technical writers, not hackers.  In JavaDoc, descriptions
are 3rd person declarative (after all, the documentation describes
what the function does, not what you want it to do).

http://java.sun.com/j2se/javadoc/writingdoccomments/

The incompatibilities with Python's NIH-standards are unfortunate, but
that's the way it is.
msg102088 - (view) Author: Fredrik Lundh (effbot) * (Python committer) Date: 2010-04-01 12:20
The missing/extra words in the findtext description is just a case of sloppy copy-editing, most likely after a quick reformatting.  Not sure why you're spending all this energy arguing about commas, though.
msg113319 - (view) Author: Florent Xicluna (flox) * (Python committer) Date: 2010-08-08 20:51
Documentation patch accepted, for the "path == XPath" confusion and clarify other points too.
http://bugs.python.org/issue6488#msg90528
msg113345 - (view) Author: Florent Xicluna (flox) * (Python committer) Date: 2010-08-08 22:23
See also patch attached to #2864 which proposes to add an XPath example to the documentation.
msg156850 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2012-03-26 18:44
New changeset e38f4cf482c7 by Eli Bendersky in branch 'default':
Issue #6488: Explain the XPath support of xml.etree.ElementTree, with code
http://hg.python.org/cpython/rev/e38f4cf482c7
msg156852 - (view) Author: Eli Bendersky (eli.bendersky) * (Python committer) Date: 2012-03-26 18:46
Closing the issue, unless someone wants to back-port this to 3.2/2.7
History
Date User Action Args
2012-03-26 18:46:58eli.benderskysetnosy: + eli.bendersky
messages: + msg156852
2012-03-26 18:46:05eli.benderskysetstatus: open -> closed
resolution: fixed
stage: needs patch -> resolved
2012-03-26 18:44:26python-devsetnosy: + python-dev
messages: + msg156850
2012-02-26 22:39:44floxlinkissue14006 dependencies
2010-08-08 22:23:47floxsetnosy: + guettli, littlemog, mbone
messages: + msg113345
2010-08-08 22:22:23floxlinkissue2864 superseder
2010-08-08 20:51:14floxsetassignee: effbot ->
type: behavior
messages: + msg113319
2010-04-01 12:20:52effbotsetmessages: + msg102088
2010-04-01 12:02:34effbotsetmessages: + msg102087
2010-03-28 22:14:20r.david.murraysetnosy: + r.david.murray
messages: + msg101875
2010-03-28 18:09:47floxsetnosy: + flox
2010-03-28 18:09:12floxsetnosy: effbot, georg.brandl, jaraco, eric.araujo, MLModel
stage: needs patch
components: + XML
versions: - Python 3.0
2010-03-28 17:26:03eric.araujosetnosy: + eric.araujo
messages: + msg101869
2010-03-28 17:16:05jaracosetnosy: + jaraco
messages: + msg101868
2009-07-15 01:36:52ezio.melottisetpriority: low
assignee: georg.brandl -> effbot

nosy: + effbot
2009-07-15 00:55:27MLModelcreate