#4100: note that element children are not necessarily present on "start" events.

diff --git a/Doc/library/xml.etree.elementtree.rst b/Doc/library/xml.etree.elementtree.rst
index cdc774ec07f64e7eda2b2006e21a710e9f9e6ef3..b17d5103aa113c994263e65c3fdf239f83bc093f 100644 (file)
--- a/Doc/library/xml.etree.elementtree.rst
+++ b/Doc/library/xml.etree.elementtree.rst
@@ -94,6 +94,16 @@ Functions
    *events* is a list of events to report back.  If omitted, only "end" events are
    reported. Returns an :term:`iterator` providing ``(event, elem)`` pairs.
 
+   .. note::
+
+      :func:`iterparse` only guarantees that it has seen the ">"
+      character of a starting tag when it emits a "start" event, so the
+      attributes are defined, but the contents of the text and tail attributes
+      are undefined at that point.  The same applies to the element children;
+      they may or may not be present.
+
+      If you need a fully populated element, look for "end" events instead.
+
 
 .. function:: parse(source[, parser])