> Just as an example: consider that in a lot of use cases the programmer will want to discard parts of the tree that's parsed iteratively (similarly to the main use case of iterparse()), because the XML itself is too huge. It's a convenient streaming API, in other words. Now, if the reader discards parts of the tree (by deleting subtrees), then returning the root from close() becomes even more meaningless, because it's no longer the root and we have no idea what it actually is.

Well, that's how the parser API works. It's the target's responsibility to make something (really, anything) of the parser's callbacks. Why change this for XMLPullParser if it already works that way for both XMLParser and iterparse() ? It's an inherent part of the design, and it really fits together just fine.

I don't like the idea of deliberately adding surprises to an otherwise simple API, especially if they clearly restrict future developments.


> Finally, I will add that we can always err on the side of under-specifying. We plan to change the implementation of the class in the future, so we can always add to the API. Specifying that close() returns the root is something we can't back out of, but we can always add in a future release without hurting backwards compatibility, if we do reach the conclusion that it's better.

Eli, if you had taken a look at my patch (and also a closer look at some of my earlier patches), you would have noticed that it not only makes close() behave as expected, but also removes the ".root" attribute from the parser. This removes a very unfortunate design decision in iterparse() that has bugged me several times in the past already, because it really gets in the way of both the implementation and the usage. Please keep that a misfeature only of iterparse() and do not repeat this mistake in this newly introduced API.

In fact, my decision to make XMLPullParser.close() consistent with XMLParser.close() was mostly motivated by this change, not the other way round.