Document DocumentBuilder parsing APIs

[jonathanpeppers]

Summary

• Document the five DocumentBuilder.ParseAsync overloads that project Java's documented XML parsing APIs.
• Replace their parameter, summary, and result placeholders without changing members covered by Document Java XML parser members #410 or Document Javax.Xml.Parsers APIs #421.

Sources

• Android DocumentBuilder reference
• Java SE 8 DocumentBuilder reference

Validation

• Parsed docs/xml/Javax.Xml.Parsers/DocumentBuilder.xml successfully as XML.
• Confirmed CRLF line endings and no remaining To be added placeholders in DocumentBuilder.ParseAsync members.
• Ran git diff --check.

Refs #280

[Copilot]

Pull request overview

Documents the five Javax.Xml.Parsers.DocumentBuilder.ParseAsync overloads by replacing placeholder XML doc text with parameter descriptions, summaries, and return descriptions aligned to the Java/Android API surface.

Changes:

• Replaced To be added. placeholders for ParseAsync parameters, summaries, and returns across five overloads.
• Preserved existing attribution/licensing remarks blocks while updating member doc content.

Suppressed comments (4)

docs/xml/Javax.Xml.Parsers/DocumentBuilder.xml:624

• The wording here deviates from the repository’s common Task documentation style ("A task that represents …") and reads as though the result is always a new/non-null document despite the nullable Task result type.

        <summary>Parses the content of the given input source as an XML document.</summary>
        <returns>A task whose result is a new DOM document.</returns>

docs/xml/Javax.Xml.Parsers/DocumentBuilder.xml:655

• The phrasing here ("A task whose result …") is inconsistent with the prevailing style in other async docs ("A task that represents …") and may overstate non-nullness given Task<…IDocument?>.

        <summary>Parses the content of the given input stream as an XML document.</summary>
        <returns>A task whose result is a new DOM document.</returns>

docs/xml/Javax.Xml.Parsers/DocumentBuilder.xml:686

• The line here doesn’t match the common Task documentation wording used elsewhere in this repo ("A task that represents …") and may imply a guaranteed new/non-null result while the signature is Task<…IDocument?>.

        <summary>Parses the content of the given URI as an XML document.</summary>
        <returns>A task whose result is a new DOM document.</returns>

docs/xml/Javax.Xml.Parsers/DocumentBuilder.xml:719

• The text here uses uncommon wording for Task-returning APIs in this repo ("whose result") and implies a new/non-null document, even though the method signature is Task<…IDocument?>.

        <summary>Parses the content of the given input stream as an XML document.</summary>
        <returns>A task whose result is a new DOM document.</returns>

---

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

[jonathanpeppers]

Addressed the automated review feedback: the ParseAsync return documentation now describes the parsing task without implying a non-null result.

[jonathanpeppers]

@dalexsoto review

[dalexsoto]

The documented API behavior matches the current contracts; no blocking issues found.