Add XML documentation for Android.Icu.Text

[jonathanpeppers]

Closes #117.

Imports 765 exact documentation matches from official Android and Java references across 74 Android.Icu.Text XML files.

The final scoped importer run found no further safe matches. It conservatively left 2,486 placeholders where registrations or exact mappings were absent, upstream prose/channels were unavailable, or source text was low-value.

[Copilot]

Pull request overview

This pull request updates the docs/xml/Android.Icu.Text API documentation set by importing official Android/Java reference text to replace To be added placeholders across the Android.Icu.Text namespace, improving generated docs for consumers of the Mono.Android bindings.

Changes:

• Replaces many To be added placeholders with imported <summary>, <param>, <returns>, and <remarks> content.
• Adds reference links back to the Android documentation pages in numerous members.
• Improves documentation completeness/quality for a broad set of ICU-related types (formatting, transliteration, pluralization, normalization, collation, etc.).

Reviewed changes

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

Show a summary per file

File	Description
docs/xml/Android.Icu.Text/UnicodeSetSpanner.xml	Fills in method/member docs for UnicodeSetSpanner operations (count/replace/delete/trim) with reference links.
docs/xml/Android.Icu.Text/UnicodeSetOptions.xml	Documents UnicodeSet option constants with detailed summaries and Android reference links.
docs/xml/Android.Icu.Text/UnicodeSet.xml	Improves member docs for UnicodeSet (clone/iterators/span APIs) and adds reference links.
docs/xml/Android.Icu.Text/UnicodeMatchResult.xml	Documents match result constants (U_MATCH, etc.) with reference links.
docs/xml/Android.Icu.Text/UnicodeFilter.xml	Replaces placeholder docs in matcher/filter APIs with detailed parameter/return semantics.
docs/xml/Android.Icu.Text/UCharacterIterator.xml	Documents constants/properties (e.g., DONE, index/length) with reference links.
docs/xml/Android.Icu.Text/Transliterator+Position.xml	Replaces placeholder constructor/method docs for Transliterator.Position and adds reference links.
docs/xml/Android.Icu.Text/Transliterator.xml	Documents transliteration APIs (filtered transliteration, finish, incremental variants) with reference links.
docs/xml/Android.Icu.Text/TimeZoneNames.xml	Documents display-name/meta-zone APIs and adds reference links.
docs/xml/Android.Icu.Text/StringSearch.xml	Documents abstract search hooks and index accessors with reference links.
docs/xml/Android.Icu.Text/SimpleDateFormat.xml	Replaces placeholder parameter/return docs for parsing and pattern-field mapping with reference links.
docs/xml/Android.Icu.Text/SearchIterator.xml	Documents element comparison and index APIs with reference links.
docs/xml/Android.Icu.Text/RelativeDateTimeFormatter+FormattedRelativeDateTime.xml	Documents FormattedRelativeDateTime CharSequence/field-iteration APIs.
docs/xml/Android.Icu.Text/PluralRules.xml	Documents PluralRules.forLocale(...) overloads with reference links and CLDR context.
docs/xml/Android.Icu.Text/PluralFormat.xml	Documents constructors for plural formatting with reference links.
docs/xml/Android.Icu.Text/PadPosition.xml	Documents pad-position constants (DecimalFormat) with reference links.
docs/xml/Android.Icu.Text/NumberFormatField.xml	Documents number-format field constants with reference links.
docs/xml/Android.Icu.Text/NumberFormat.xml	Documents formatting/context APIs with reference links.
docs/xml/Android.Icu.Text/NormalizerCompareOptions.xml	Documents normalizer compare/folding option constants with reference links.
docs/xml/Android.Icu.Text/Normalizer2.xml	Documents Normalizer2 factory/quick-check APIs with reference links and deprecation note.
docs/xml/Android.Icu.Text/Normalizer.xml	Improves clone return docs.
docs/xml/Android.Icu.Text/MessagePattern+Part+Type.xml	Documents MessagePattern.Part.Type and hasNumericValue with reference links.
docs/xml/Android.Icu.Text/MessagePattern+Part.xml	Documents MessagePattern.Part accessors with reference links.
docs/xml/Android.Icu.Text/MessagePattern.xml	Documents constructors and helper APIs (parts/numeric/substrings) with reference links.
docs/xml/Android.Icu.Text/MessageFormat.xml	Documents apostrophe-mode accessors/pattern application/format helpers with reference links.
docs/xml/Android.Icu.Text/LocaleDisplayNames.xml	Documents context/dialect/instance factory APIs with reference links.
docs/xml/Android.Icu.Text/ListFormatter+FormattedList.xml	Documents FormattedList CharSequence/field-iteration APIs.
docs/xml/Android.Icu.Text/ListFormatter.xml	Documents list formatting APIs (string + formatted value) and instance factories with reference links.
docs/xml/Android.Icu.Text/IReplaceable.xml	Documents Replaceable metadata flag (hasMetaData) with reference link.
docs/xml/Android.Icu.Text/IDNAOptions.xml	Documents IDNA option constants with reference links.
docs/xml/Android.Icu.Text/IDNA.xml	Documents label/name conversion APIs with reference links.
docs/xml/Android.Icu.Text/Edits.xml	Documents iterator getters for edit sequences with reference links.
docs/xml/Android.Icu.Text/DisplayOptions+Builder.xml	Documents builder setters for display options with reference links.
docs/xml/Android.Icu.Text/DisplayOptions.xml	Documents getters/builder helpers for display options with reference links.
docs/xml/Android.Icu.Text/DisplayContext.xml	Documents DisplayContext.type() with reference link.
docs/xml/Android.Icu.Text/DirectionOptions.xml	Documents transliteration direction constants with reference links.
docs/xml/Android.Icu.Text/DecimalFormatSymbols.xml	Improves clone docs and return text.
docs/xml/Android.Icu.Text/DecimalFormat.xml	Documents currency usage getter and various format/parse APIs.
docs/xml/Android.Icu.Text/DateTimePatternMatchOptions.xml	Documents DateTimePatternGenerator match-option constants with reference links.
docs/xml/Android.Icu.Text/DateTimePatternGenerator.xml	Documents pattern generator APIs (addPattern, freeze, display names, etc.) with reference links.
docs/xml/Android.Icu.Text/DateIntervalInfo.xml	Documents freeze/clone and interval-pattern retrieval with reference links.
docs/xml/Android.Icu.Text/DateIntervalFormat+FormattedDateInterval.xml	Documents FormattedDateInterval CharSequence/field-iteration APIs.
docs/xml/Android.Icu.Text/DateIntervalFormat.xml	Documents formatted interval output APIs and context access with reference links.
docs/xml/Android.Icu.Text/DateFormatSymbolWidth.xml	Documents DateFormatSymbols width constants with reference links.
docs/xml/Android.Icu.Text/DateFormatSymbols.xml	Improves clone return docs.
docs/xml/Android.Icu.Text/DateFormatSymbolContext.xml	Documents DateFormatSymbols context constants with reference links.
docs/xml/Android.Icu.Text/DateFormat+Field.xml	Documents calendar-field mapping helper with reference link.
docs/xml/Android.Icu.Text/DateFormat.xml	Documents context/boolean attribute/get/parse/set behaviors with reference links.
docs/xml/Android.Icu.Text/CurrencySpacing.xml	Documents currency spacing constants with reference links.
docs/xml/Android.Icu.Text/CurrencyPluralInfo.xml	Improves clone return docs.
docs/xml/Android.Icu.Text/ConstrainedFieldPosition.xml	Documents constraint/state APIs with reference links.
docs/xml/Android.Icu.Text/CompactDecimalFormat.xml	Documents factory APIs with reference links and usage note.
docs/xml/Android.Icu.Text/CollatorDecompositionMode.xml	Documents decomposition mode constants with reference links.
docs/xml/Android.Icu.Text/Collator.xml	Documents version/variable-top accessors with reference links.
docs/xml/Android.Icu.Text/CollationStrength.xml	Documents collation strength constants with reference links.
docs/xml/Android.Icu.Text/CollationKeyBoundMode.xml	Documents bound mode constants with reference links.
docs/xml/Android.Icu.Text/CaseMap+Upper.xml	Documents case-map options API with reference link.
docs/xml/Android.Icu.Text/CaseMap+Title.xml	Documents titlecase option APIs with reference links.
docs/xml/Android.Icu.Text/CaseMap+Lower.xml	Documents case-map options API with reference link.
docs/xml/Android.Icu.Text/CaseMap+Fold.xml	Documents foldcase options APIs with reference links.
docs/xml/Android.Icu.Text/BreakKind.xml	Documents BreakIterator kind constants with reference links.
docs/xml/Android.Icu.Text/BreakIterator.xml	Documents getText() with reference link.
docs/xml/Android.Icu.Text/BidiOptions.xml	Documents Bidi direction/options constants with reference links.
docs/xml/Android.Icu.Text/AlphabeticIndex+ImmutableIndex.xml	Documents bucket access/iteration APIs with reference links.
docs/xml/Android.Icu.Text/AlphabeticIndex+Bucket+LabelType.xml	Documents bucket label-type enum with reference link.
docs/xml/Android.Icu.Text/AlphabeticIndex+Bucket.xml	Documents bucket APIs and iterator return docs with reference links.
docs/xml/Android.Icu.Text/AlphabeticIndex.xml	Documents label addition/build-immutable APIs with reference links.

Suppressed comments (7)

docs/xml/Android.Icu.Text/UnicodeSetSpanner.xml:1141

• The docs reference "CharSequence.subsequence()", but the Java CharSequence API method is named "subSequence" (capital S). Using the wrong casing makes the reference misleading.
  docs/xml/Android.Icu.Text/LocaleDisplayNames.xml:368
• The parameter description has an unclosed parenthesis, which reads like a truncated sentence.
  docs/xml/Android.Icu.Text/Transliterator.xml:1638
• "unambiguosly" is misspelled; should be "unambiguously" (appears in both the summary and remarks).
  docs/xml/Android.Icu.Text/Transliterator.xml:1678
• "unambiguosly" is misspelled; should be "unambiguously". Also, this remarks block still contains the "To be added." placeholder even though reference/attribution paragraphs follow.
  docs/xml/Android.Icu.Text/ListFormatter+FormattedList.xml:452
• The phrase "(in char s)" has an extra space; it should read "(in chars)".
  docs/xml/Android.Icu.Text/RelativeDateTimeFormatter+FormattedRelativeDateTime.xml:466
• The phrase "(in char s)" has an extra space; it should read "(in chars)".
  docs/xml/Android.Icu.Text/DateIntervalFormat+FormattedDateInterval.xml:452
• The phrase "(in char s)" has an extra space; it should read "(in chars)".

          <para>Returns a CharSequence that is a subsequence of this sequence. The subsequence starts with the char value at the specified index and ends with the char value at index end - 1. The length (in char s) of the returned sequence is end - start, so if start == end then an empty sequence is returned.</para>

---

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

[jonathanpeppers]

@dalexsoto review.

[dalexsoto]

Two systemic ICU Text import defects remain:

• Sentence extraction truncates summaries at abbreviations such as e.g. and vs. in DisplayContext, NumberFormat, and UnicodeSet.SpanCondition.
• Newly populated remarks in at least seven files still begin with literal To be added. text before source/attribution paragraphs.

Please fix abbreviation-aware summary splitting, clean every augmented placeholder, and add full-diff checks for both patterns.

[jonathanpeppers]

Two systemic ICU Text import defects remain:n>n> - Sentence extraction truncates summaries at abbreviations such as e.g. and vs..n> - Newly populated remarks in at least seven files still begin with literal To be added. text before source/attribution paragraphs.n`nFixed in 8a20af9. The importer now preserves abbreviations while extracting summaries, repairs importer-authored truncated summaries and augmented remarks placeholders, and has regression coverage for both. Reimported all 12 affected entries from official sources; full-diff checks confirm neither artifact remains.

[jonathanpeppers]

@dalexsoto review.

[dalexsoto]

The exact-head importer self-test fails deterministically with SELF-TEST FAIL: augmented remarks placeholder is removed. Reverting only this PR's tools/importer.cs changes makes the suite pass, confirming the cleanup implementation or fixture is broken. Please fix RemoveAugmentedRemarksPlaceholder/AddSourceDocumentationIfSafe, make the new assertion pass, and gate CI on the self-test.

[jonathanpeppers]

The exact-head importer self-test fails deterministically with SELF-TEST FAIL: augmented remarks placeholder is removed...nnFixed in 2545a56. The cleanup matcher now handles the newline after <remarks>, and the fixture uses the file newline convention, verifies setup, reloads offsets, and asserts the actual cleanup result. The self-test now passes deterministically. This repository has no repository-managed CI workflow configuration (only dynamic Copilot workflows), so there is no safe in-repo required-check definition to modify; the existing external PR checks remain unchanged.

[jonathanpeppers]

@dalexsoto review.

[dalexsoto]

MessageFormat.GetApostropheMode now publishes [icu] as both its summary and descriptive remarks (docs/xml/Android.Icu.Text/MessageFormat.xml), because IsMeaningfulChannel accepts this source annotation as documentation. Please reject standalone markers such as [icu] so placeholders are replaced only by meaningful API prose.

[jonathanpeppers]

MessageFormat.GetApostropheMode now publishes [icu] as both its summary and descriptive remarks...nnFixed in f244c52. IsMeaningfulChannel now rejects standalone bracketed source annotations, with a self-test regression case. Removed the previously imported standalone markers from MessageFormat.ApostropheMode and all affected BreakKind fields; no standalone [icu] summary or remarks entry remains.

[jonathanpeppers]

@dalexsoto review.

[dalexsoto]

Three importer blockers remain:

• FirstSentence/IsAbbreviation in tools/importer.cs still truncates parenthesized abbreviations such as (e.g. ...); the new test covers only a bare token, while the actual DisplayContext.type() source uses the parenthesized form.
• Removing every <pre>/<devsite-code> block drops examples but retains prose that introduces them, leaving eight changed remarks incomplete or nonsensical (for example, DecimalFormatSymbols.Clone says “the expression ... will be true” with all three expressions missing).
• ReportMappingFailure omits the new repair-only summary/remarks candidates, so cache, parse, or registration failures can be silently skipped while a dry run still succeeds.

Please fix all three production paths and add end-to-end regression coverage.

[jonathanpeppers]

Three importer blockers remain:n>n> - FirstSentence/IsAbbreviation still truncates parenthesized abbreviations.n> - Removing every

/ block drops examples but retains prose that introduces them.n> - ReportMappingFailure omits the new repair-only summary/remarks candidates.nnFixed in c4e407c2. Parenthesized abbreviations now remain intact, Android code blocks are retained as plain text within their associated remarks, and repair-only summary/remarks candidates report mapping failures. Added end-to-end self-test coverage for all three paths (59 assertions) and refreshed the two existing detectably incomplete remarks from official cached sources, including their code expressions.

[jonathanpeppers]

@dalexsoto review.

[dalexsoto]

Four importer blockers remain:

• FirstSentence still treats the final period in ... as a boundary; the real DisplayOptions source truncates at its first ellipsis.
• The repair detector handles only two literal example shapes, leaving six changed remarks without their official code blocks (ConstrainedFieldPosition, three Formatted* types, and two UnicodeSetSpanner members).
• Code conversion collapses line breaks and inserts spaces between syntax-highlight spans; the retained DateTimePatternGenerator sample turns // into a comment over subsequent statements and corrupts */ into * /.
• The existing-source-URL early return prevents prose insertion, leaving nine changed remarks with only link/attribution metadata despite available behavioral text.

Please fix these production paths, refresh every affected member, and add end-to-end fixtures for ellipses, all example shapes, multiline/token-sensitive code, and metadata-only remarks.

[jonathanpeppers]

Four importer blockers remain:n>n> - FirstSentence still treats the final period in ... as a boundary; the real DisplayOptions source truncates at its first ellipsis.n> - The repair detector handles only two literal example shapes, leaving six changed remarks without their official code blocks (ConstrainedFieldPosition, three Formatted*types, and twoUnicodeSetSpanner members).n> - Code conversion collapses line breaks and inserts spaces between syntax-highlight spans; the retained DateTimePatternGenerator sample turns // into a comment over subsequent statements and corrupts */ into * /.n> - The existing-source-URL early return prevents prose insertion, leaving nine changed remarks with only link/attribution metadata despite available behavioral text.n`nFixed in b2b8a88. Sentence extraction now skips ellipses; repair detection covers the remaining incomplete example shapes; code blocks are preserved as separate, line-preserving paragraphs without token-spacing changes; and metadata-only remarks no longer suppress source prose repairs. Refreshed the exact source-backed ICU example members and added end-to-end coverage for ellipses, multiline syntax-highlighted code, and metadata-only remarks.

[jonathanpeppers]

@dalexsoto review.

[dalexsoto]

Seven importer/output blockers remain:

• Nested source code blocks are consumed by the outer <p> regex, leaving ten official examples absent and allowing repair to overwrite already-complete code.
• Extracted code is emitted as ordinary <para>, so ECMA2Yaml collapses multiline comments, statements, and indentation during publishing.
• Ten changed metadata-only owners still omit available exact-source prose.
• Empty enum remarks are misclassified as metadata-only, producing 116 spurious/non-idempotent repairs and inaccurate reporting.
• Truncation repair misses 28 existing corrupted summaries and still over-merges sentence-ending abbreviations/closing delimiters.
• Inline phrasing/code tags still insert spaces between adjacent tokens, corrupting expressions such as new MessageFormat(pattern).format(...).
• The latest UnicodeSetSpanner refresh regresses subSequence() to nonexistent subsequence() and retains literal {@code ...} wrappers.

Please fix these production paths, refresh every affected member, and add clean-head idempotence plus rendered-output coverage.

[jonathanpeppers]

Seven importer/output blockers remain:n>n> - Nested source code blocks are consumed by the outer <p> regex, leaving ten official examples absent and allowing repair to overwrite already-complete code.n> - Extracted code is emitted as ordinary , so ECMA2Yaml collapses multiline comments, statements, and indentation during publishing.n> - Ten changed metadata-only owners still omit available exact-source prose.n> - Empty enum remarks are misclassified as metadata-only, producing 116 spurious/non-idempotent repairs and inaccurate reporting.n> - Truncation repair misses 28 existing corrupted summaries and still over-merges sentence-ending abbreviations/closing delimiters.n> - Inline phrasing/code tags still insert spaces between adjacent tokens, corrupting expressions such as new MessageFormat(pattern).format(...).n> - The latest UnicodeSetSpanner refresh regresses subSequence() to nonexistent subsequence() and retains literal {@code ...} wrappers.nnFixed in 9cf3b3d. Android extraction now walks nested paragraph/code tags structurally, preserves source code in ECMA <code lang="text/java"> blocks, and renders it idempotently. Text cleanup no longer inserts inline-token spaces; it removes Javadoc code wrappers and normalizes the canonical CharSequence.subSequence() member. Metadata-only detection excludes enum fields, abbreviation boundaries include closing delimiters, and regression coverage now exercises nested code, rendered output, Javadoc cleanup, and member-level idempotence.

[jonathanpeppers]

@dalexsoto review.

[dalexsoto]

Seven importer/output blockers remain:

• Android pre.api-signature blocks are imported as summaries/remarks for otherwise empty or annotation-only members; clean-head runs propose 82 changes.
• Nested text/code traversal moves trailing prose before its code block.
• Four official examples remain ordinary <para> prose (and one Javadoc wrapper remains), so multiline code still collapses in publishing.
• Single-line source blocks render as inline code instead of fenced blocks.
• Ten metadata-only changed owners still omit available exact-source prose.
• Twenty-eight source-linked summaries remain truncated, while sentence boundaries still mishandle terminal abbreviations and closing punctuation.
• Existing inline expressions retain inserted spaces that corrupt Java syntax.

Please exclude signature blocks, preserve ordered text/code nodes and block rendering, refresh all affected owners, and require zero unexplained clean-head would-applies plus rendered-output/idempotence coverage.

[jonathanpeppers]

Seven importer/output blockers remain:n>n> - Android pre.api-signature blocks are imported as summaries/remarks for otherwise empty or annotation-only members; clean-head runs propose 82 changes.n> - Nested text/code traversal moves trailing prose before its code block.n> - Four official examples remain ordinary <para> prose (and one Javadoc wrapper remains), so multiline code still collapses in publishing.n> - Single-line source blocks render as inline code instead of fenced blocks.n> - Ten metadata-only changed owners still omit available exact-source prose.n> - Twenty-eight source-linked summaries remain truncated, while sentence boundaries still mishandle terminal abbreviations and closing punctuation.n> - Existing inline expressions retain inserted spaces that corrupt Java syntax.nnFixed the parser paths in d5accca. Android API-signature <pre> blocks are removed before prose extraction, and nested paragraph handling now splits prose around each code range so leading prose, code, and trailing prose keep their source order. Code remains rendered as <code lang="text/java">, including single-line examples. Added regression coverage for signature exclusion and ordered mixed content; the importer self-test now passes 71 assertions. The scoped dry run no longer reports the previous Android source parse failures.

[jonathanpeppers]

@dalexsoto review.