Document TextUtils string splitter iteration

[jonathanpeppers]

Refs #223

Summary

• Document the source-defined return contracts for TextUtils.SimpleStringSplitter iteration members: HasNext, Iterator, and both Next bindings.
• Clarify that Iterator() returns the splitter instance itself because it is its own iterator.
• Keep JniPeerMembers binding-infrastructure placeholders and the rest of Android.Text out of scope.
• The issue remains open: 1,878 To be added. placeholders remain in Android.Text XML documentation.

Sources

• https://developer.android.com/reference/android/text/TextUtils.SimpleStringSplitter
• https://developer.android.com/reference/java/lang/Iterable#iterator()
• https://developer.android.com/reference/java/util/Iterator#next()
• https://android.googlesource.com/platform/frameworks/base/+/refs/heads/main/core/java/android/text/TextUtils.java (SimpleStringSplitter.iterator() implementation; used for the instance-identity detail absent from the Android reference page)

Validation

• Parsed docs/xml/Android.Text/TextUtils+SimpleStringSplitter.xml with PowerShell [xml].
• Confirmed CRLF-only line endings (0 bare LF) in the changed file.
• Ran git diff --check and reviewed the complete diff after each change.

[Copilot]

Pull request overview

This PR updates the XML documentation for Android.Text.TextUtils.SimpleStringSplitter iteration-related members to replace To be added. placeholders with concrete return/value contracts.

Changes:

• Documented the HasNext property value contract (true/false meaning).
• Replaced placeholder return docs for Iterator() and both Next bindings with specific return descriptions.

Suppressed comments (2)

docs/xml/Android.Text/TextUtils+SimpleStringSplitter.xml:211

• Iterator.next() is specified to throw NoSuchElementException when there are no more elements. This binding doc omits the exception contract; adding it aligns with the standard java.util.Iterator.next() contract and other iterator docs in this repo.

This issue also appears on line 269 of the same file.

        <returns>The next element in the iteration.</returns>
        <remarks>
          <para>Portions of this page are modifications based on work created and shared by the <format type="text/html"><a href="https://developers.google.com/terms/site-policies" title="Android Open Source Project">Android Open Source Project</a></format> and used according to terms described in the <format type="text/html"><a href="https://creativecommons.org/licenses/by/2.5/" title="Creative Commons 2.5 Attribution License">Creative Commons 2.5 Attribution License.</a></format></para>
        </remarks>
      </Docs>

docs/xml/Android.Text/TextUtils+SimpleStringSplitter.xml:273

• next() is specified to throw NoSuchElementException when called after iteration is exhausted. This doc update improves the return contract but still omits the exception contract; add it to match the java.util.Iterator.next() contract and other iterator docs in this repo.

        <returns>The next element in the iteration.</returns>
        <remarks>
          <para>Portions of this page are modifications based on work created and shared by the <format type="text/html"><a href="https://developers.google.com/terms/site-policies" title="Android Open Source Project">Android Open Source Project</a></format> and used according to terms described in the <format type="text/html"><a href="https://creativecommons.org/licenses/by/2.5/" title="Creative Commons 2.5 Attribution License">Creative Commons 2.5 Attribution License.</a></format></para>
        </remarks>
        <since version="Added in API level 1" />

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[jonathanpeppers]

@dalexsoto review