getText() underspecified

The JavaDoc for the getText method in XmlPullParser states:

Returns the text content of the current event as String.

IMO, this is insufficent. It is not clear what the
text content of the current event actually is.
In some cases, pieces are left out. In other cases they're not.
In my tests with XPP3, I noted the following behavior:

     * For tags, it's the complete actual tag.
     * For entity references, it's the entity replacement text (or null if not available).
     * For text and ignorable white space, it's the actual text
     * For CDATA sections, it's the text inside the CDATA section delimiters, that is, between <![CDATA[ and ]]>
     * For start and end document, it's null
     * For comments, it's the content of the comment inside the <-- and -->.
     * For processing instructions, it's the content of the instruction inside the <? and ?>.
     * For document type declarations, it's the content of the DOCTYPE declaration between <!DOCTYPE and the closing >.

However, other parsers could easily do something
different and still claim to be adhering to the spec.
For instance, they might include the CDATA section
delimiters or not inlcude the brackets around a tag.

I suggest, the issue of exactly what getText() does and does
not return be discussed and documented for each event type.