Document XML datatype APIs

[jonathanpeppers]

Summary

• Document source-backed DatatypeFactory, Duration, and XMLGregorianCalendar property values, factory parameters, and conversion results.
• Leave DatatypeConstants.xml untouched because an active concurrent worktree owns that file.
• Exclude generated JniPeerMembers infrastructure placeholders, which have no Java API source counterpart.

Sources

• Android DatatypeFactory reference
• Android Duration reference
• Android XMLGregorianCalendar reference
• OpenJDK datatype sources

Validation

• Parsed all changed XML files with PowerShell's XML parser.
• Ran git diff --check.
• Confirmed CRLF line endings on each changed XML file.

[Copilot]

Pull request overview

This PR improves the generated XML documentation for javax.xml.datatype APIs by replacing placeholder docs with source/reference-backed descriptions for key DatatypeFactory, Duration, and XMLGregorianCalendar members.

Changes:

• Filled in previously placeholder <value> documentation for several XMLGregorianCalendar fields (day/month/second/timezone/year components).
• Updated Duration member docs to describe return/value semantics (e.g., hash code and sign).
• Updated DatatypeFactory docs for the default implementation constant and the newInstance(String, ClassLoader) parameters.

Reviewed changes

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

File	Description
docs/xml/Javax.Xml.Datatype/XMLGregorianCalendar.xml	Replaces placeholder value docs for multiple calendar fields and schema type info.
docs/xml/Javax.Xml.Datatype/Duration.xml	Replaces placeholder return/value docs for selected members.
docs/xml/Javax.Xml.Datatype/DatatypeFactory.xml	Improves constant/value docs and factory method parameter docs.

Suppressed comments (6)

docs/xml/Javax.Xml.Datatype/XMLGregorianCalendar.xml:611

• This value references FieldUndefined using ..., which renders as plain code and loses the cross-reference. Elsewhere in this file the constant is referenced with ; please keep that pattern for consistency and navigability.

        <value>The hour of day, from 0 to 23, or <c>DatatypeConstants.FieldUndefined</c> if undefined.</value>

docs/xml/Javax.Xml.Datatype/XMLGregorianCalendar.xml:766

• This value references FieldUndefined using ..., which renders as plain code and loses the cross-reference. Elsewhere in this file the constant is referenced with ; please keep that pattern for consistency and navigability.

        <value>The month, from 1 to 12, or <c>DatatypeConstants.FieldUndefined</c> if undefined.</value>

docs/xml/Javax.Xml.Datatype/XMLGregorianCalendar.xml:803

• This value references FieldUndefined using ..., which renders as plain code and loses the cross-reference. Elsewhere in this file the constant is referenced with ; please keep that pattern for consistency and navigability.

        <value>The second of minute, from 0 to 59, or <c>DatatypeConstants.FieldUndefined</c> if undefined.</value>

docs/xml/Javax.Xml.Datatype/XMLGregorianCalendar.xml:969

• This value references FieldUndefined using ..., which renders as plain code and loses the cross-reference. Elsewhere in this file the constant is referenced with ; please keep that pattern for consistency and navigability.

        <value>The timezone offset in minutes, or <c>DatatypeConstants.FieldUndefined</c> if undefined.</value>

docs/xml/Javax.Xml.Datatype/XMLGregorianCalendar.xml:1327

• This value references FieldUndefined using ..., which renders as plain code and loses the cross-reference. Elsewhere in this file the constant is referenced with ; please keep that pattern for consistency and navigability.

        <value>The timezone offset in minutes, or <c>DatatypeConstants.FieldUndefined</c> if undefined.</value>

docs/xml/Javax.Xml.Datatype/XMLGregorianCalendar.xml:1640

• This value references FieldUndefined using ..., which renders as plain code and loses the cross-reference. Elsewhere in this file the constant is referenced with ; please keep that pattern for consistency and navigability.

        <value>The low-order component of the year, or <c>DatatypeConstants.FieldUndefined</c> if undefined.</value>

---

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

[jonathanpeppers]

@dalexsoto review

[dalexsoto]

Several newly added values describe the wrong public contract:

• docs/xml/Javax.Xml.Datatype/XMLGregorianCalendar.xml: Minute is documented as a month, Month as seconds, and Second as a timezone offset. Please assign the correct ranges to each property. The Hour range must also include 24, with the constraint that minutes and seconds are zero.
• docs/xml/Javax.Xml.Datatype/DatatypeFactory.xml: NewInstance(string, ClassLoader) says it returns DocumentBuilderFactory, but the declared return type is DatatypeFactory. Please correct the return text.