Document Javax.Xml.Parsers APIs

[jonathanpeppers]

Closes #280

Sources

• Android SAXParser reference
• AOSP SAXParser.java for the parser overload descriptions and parameter semantics
• .NET for Android JniPeerMembers reference for binding runtime metadata

Validation

• Parsed all six changed XML files with System.Xml.XmlDocument.
• Confirmed scoped To be added. placeholders: 52 before, 0 after.
• Confirmed CRLF line endings for every scoped XML file.
• Ran git diff --check and confirmed the diff is limited to docs/xml/Javax.Xml.Parsers/.

[Copilot]

Pull request overview

Updates the generated XML reference documentation for the Javax.Xml.Parsers namespace, replacing To be added. placeholders with meaningful API docs to improve the .NET for Android developer reference (closes #280).

Changes:

• Adds parameter/summary/returns documentation for SAXParser.ParseAsync(...) overloads.
• Replaces To be added. placeholders for JniPeerMembers property docs across multiple Javax.Xml.Parsers types.
• Removes placeholder-only remarks blocks in some JniPeerMembers entries.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
docs/xml/Javax.Xml.Parsers/SAXParserFactory.xml	Updates JniPeerMembers docs for SAXParserFactory.
docs/xml/Javax.Xml.Parsers/SAXParser.xml	Documents multiple ParseAsync overloads (params/summary/returns).
docs/xml/Javax.Xml.Parsers/ParserConfigurationException.xml	Updates JniPeerMembers docs for ParserConfigurationException.
docs/xml/Javax.Xml.Parsers/FactoryConfigurationError.xml	Updates JniPeerMembers docs for FactoryConfigurationError.
docs/xml/Javax.Xml.Parsers/DocumentBuilderFactory.xml	Updates JniPeerMembers docs for DocumentBuilderFactory.
docs/xml/Javax.Xml.Parsers/DocumentBuilder.xml	Updates JniPeerMembers docs for DocumentBuilder.

Suppressed comments (9)

docs/xml/Javax.Xml.Parsers/SAXParser.xml:894

• This is a ParseAsync overload; the summary currently reads like a synchronous API. Updating it to start with “Asynchronously …” makes the behavior clear and matches existing async documentation phrasing.

        <summary>Parses the XML content of the specified file using the specified <c>org.xml.sax.helpers.DefaultHandler</c>.</summary>

docs/xml/Javax.Xml.Parsers/SAXParser.xml:927

• For ParseAsync methods, summaries should call out asynchronous behavior to avoid confusing them with the synchronous Parse overloads.

        <summary>Parses the specified <c>org.xml.sax.InputSource</c> as XML using the specified <c>org.xml.sax.HandlerBase</c>.</summary>

docs/xml/Javax.Xml.Parsers/SAXParser.xml:1059

• For clarity and consistency with other async docs in the repo, ParseAsync summaries should begin with “Asynchronously …”.

        <summary>Parses the XML content described by the Uniform Resource Identifier (URI) using the specified <c>org.xml.sax.HandlerBase</c>.</summary>

docs/xml/Javax.Xml.Parsers/SAXParser.xml:960

• This ParseAsync overload summary should explicitly state it parses asynchronously, to align with typical .NET Async naming/documentation and other async APIs in this repo.

        <summary>Parses the specified <c>org.xml.sax.InputSource</c> as XML using the specified <c>org.xml.sax.helpers.DefaultHandler</c>.</summary>

docs/xml/Javax.Xml.Parsers/SAXParser.xml:993

• Because this is ParseAsync, the summary should use “Asynchronously parses …” so it’s not mistaken for the synchronous Parse overload.

        <summary>Parses the XML content of the input stream using the specified <c>org.xml.sax.HandlerBase</c>.</summary>

docs/xml/Javax.Xml.Parsers/SAXParser.xml:1026

• The summary should reflect that this is an asynchronous operation (ParseAsync) and not the synchronous Parse overload.

        <summary>Parses the XML content of the input stream using the specified <c>org.xml.sax.helpers.DefaultHandler</c>.</summary>

docs/xml/Javax.Xml.Parsers/SAXParser.xml:1092

• This ParseAsync overload’s summary should explicitly describe asynchronous parsing to match the method name and return type.

        <summary>Parses the XML content described by the Uniform Resource Identifier (URI) using the specified <c>org.xml.sax.helpers.DefaultHandler</c>.</summary>

docs/xml/Javax.Xml.Parsers/SAXParser.xml:1127

• Because this API is ParseAsync, the summary should explicitly say it parses asynchronously to avoid ambiguity with Parse(Stream, …).

        <summary>Parses the XML content of the input stream using the specified <c>org.xml.sax.HandlerBase</c>.</summary>

docs/xml/Javax.Xml.Parsers/SAXParser.xml:1162

• This ParseAsync overload’s summary should explicitly indicate asynchronous parsing for consistency with Async method naming and existing async summaries in the docs.

        <summary>Parses the XML content of the input stream using the specified <c>org.xml.sax.helpers.DefaultHandler</c>.</summary>

---

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

[jonathanpeppers]

@dalexsoto review

[dalexsoto]

The parser contracts, asynchronous summaries, managed signatures, and attribution now match the Android and OpenJDK behavior.