Warn about a fixed bug in XmlPullParser.nextText()

Bug: http://code.google.com/p/android/issues/detail?id=21425
Change-Id: I4c69d67bb8bfdf3f78359d800860d5dc2e2e349f

1 files changed, 10 insertions, 1 deletions

diff --git a/xml/src/main/java/org/xmlpull/v1/XmlPullParser.java b/xml/src/main/java/org/xmlpull/v1/XmlPullParser.java
index 36e6025..308c006 100644
--- a/xml/src/main/java/org/xmlpull/v1/XmlPullParser.java
+++ b/xml/src/main/java/org/xmlpull/v1/XmlPullParser.java
@@ -1051,7 +1051,7 @@ public interface XmlPullParser {
      * If current event is START_TAG then if next element is TEXT then element content is returned
      * or if next event is END_TAG then empty string is returned, otherwise exception is thrown.
      * After calling this function successfully parser will be positioned on END_TAG.
-     *
+     * 
      * <p>The motivation for this function is to allow to parse consistently both
      * empty elements and elements that has non empty content, for example for input: <ol>
      * <li>&lt;tag&gt;foo&lt;/tag&gt;
@@ -1089,6 +1089,15 @@ public interface XmlPullParser {
      *       "parser must be on START_TAG or TEXT to read text", this, null);
      *  }
      * </pre>
+     *
+     * <p><strong>Warning:</strong> Prior to API level 14, the pull parser returned by {@code
+     * android.util.Xml} did not always advance to the END_TAG event when this method was called.
+     * Work around by using manually advancing after calls to nextText(): <pre>
+     *  String text = xpp.nextText();
+     *  if (xpp.getEventType() != XmlPullParser.END_TAG) {
+     *      xpp.next();
+     *  }
+     * </pre>
      */
     String nextText() throws XmlPullParserException, IOException;