Import source-backed Android.Telephony documentation

[jonathanpeppers]

Summary

Android.Telephony still contains a large number of placeholder documentation nodes, but filling them safely requires exact mapping to authoritative Android or Java API members rather than inferred or generic prose.

This change adds a conservative file-based C# importer and uses it to replace 1,189 placeholders across 125 Android.Telephony XML files. The importer matches managed members through type registrations, JNI names and descriptors, and JniField owner metadata; imports only documented channels from exact declared members; preserves existing prose and CRLF formatting; and reports ambiguous, inherited-only, managed-only, undocumented, or low-value source channels instead of guessing.

The command is dry-run by default and includes explicit apply scope, change limits, bounded fetching with retry/backoff and caching, offline operation, deterministic JSON/text reports, and local fixture self-tests. A post-apply dry-run is idempotent with zero additional changes.

Validation

• 21 local fixture assertions pass for Android and Java methods/fields, mismatch and low-value channel skipping, XML preservation, source attribution, and CRLF atomic writes.
• All 125 changed XML files parse successfully and retain CRLF line endings.
• git diff --check passes.
• docs/xml/index.xml is unchanged.
• Added documentation was audited to reject type-only, nullability-only, See also, raw Javadoc, and generic fallback text.

Notes

2,024 placeholders remain intentionally untouched because authoritative pages or repository metadata do not support a high-confidence import. These include managed-only projections, exact official members with no usable prose, missing type registrations, low-value source channels, inherited-only members, and missing type descriptions.

Refs #230

[jonathanpeppers]

@dalexsoto review

[jonathanpeppers]

@dalexsoto review

[Copilot]

Pull request overview

Adds a new conservative XML-doc importer workflow under tools/ and applies it to replace a large set of To be added. placeholders in docs/xml/Android.Telephony, aiming to import authoritative text from official Android/Java reference sources while preserving existing prose and formatting.

Changes:

• Added importer documentation plus local fixtures intended to validate importer behavior.
• Replaced many To be added. placeholders across Android.Telephony XML docs with imported summaries/params/remarks and reference links.
• Added/expanded remarks content for many members (including Parcelable patterns like describeContents() / writeToParcel(...)).

Reviewed changes

Copilot reviewed 129 out of 130 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
tools/importer.md	Documents how to run the XML documentation importer.
tools/importer-fixtures/source.xml	Fixture XML used to validate member matching and placeholder replacement behavior.
tools/importer-fixtures/java-reference.html	Fixture Java reference HTML used by importer tests.
tools/importer-fixtures/android-reference.html	Fixture Android reference HTML used by importer tests.
docs/xml/Android.Telephony/VisualVoicemailSmsFilterSettings+Builder.xml	Imports docs for builder methods; adds remarks and Android reference links.
docs/xml/Android.Telephony/VisualVoicemailSmsFilterSettings.xml	Imports docs for Parcelable methods like describeContents() / writeToParcel(...).
docs/xml/Android.Telephony/VisualVoicemailSms.xml	Imports docs for Parcelable methods and property value docs.
docs/xml/Android.Telephony/VisualVoicemailService.xml	Imports docs for service binding methods.
docs/xml/Android.Telephony/UssdResultCode.xml	Replaces placeholder summaries/remarks for USSD error constants.
docs/xml/Android.Telephony/UsageSetting.xml	Replaces placeholder summaries with imported text + reference links.
docs/xml/Android.Telephony/UiccPortInfo.xml	Imports Parcelable docs and value docs for UICC port info.
docs/xml/Android.Telephony/UiccCardInfo.xml	Imports Parcelable docs for UICC card info.
docs/xml/Android.Telephony/TelephonyScanManager+NetworkScanCallback.xml	Imports callback parameter docs and adds Android reference links.
docs/xml/Android.Telephony/TelephonyScanManager.xml	Replaces constructor placeholders with imported remarks + reference link/attribution.
docs/xml/Android.Telephony/TelephonyManagerErrorCode.xml	Imports constant documentation + reference links.
docs/xml/Android.Telephony/TelephonyDisplayInfo.xml	Imports Parcelable docs + reference link/attribution.
docs/xml/Android.Telephony/TelephonyCallback+IDataActivityListener.xml	Imports parameter docs for callback listener methods.
docs/xml/Android.Telephony/TelephonyCallback.xml	Replaces constructor placeholders with imported remarks + reference link/attribution.
docs/xml/Android.Telephony/SubscriptionType.xml	Imports constant summaries/remarks + reference links.
docs/xml/Android.Telephony/SubscriptionStatus.xml	Imports constant summaries/remarks + reference links.
docs/xml/Android.Telephony/SubscriptionManager.xml	Imports some param/return docs and adds Android reference links.
docs/xml/Android.Telephony/SubscriptionInfo.xml	Imports Parcelable docs (describeContents, writeToParcel) + reference links.
docs/xml/Android.Telephony/SmsMessage+MessageClass.xml	Imports return/value docs and adds Android reference link/attribution.
docs/xml/Android.Telephony/SmsMessage.xml	Imports return type docs for factory/accessor methods.
docs/xml/Android.Telephony/SmsManager.xml	Imports parameter docs for PendingIntent params and other placeholders.
docs/xml/Android.Telephony/SmsEncoding.xml	Imports constant summaries/remarks + reference links.
docs/xml/Android.Telephony/SignalThresholdInfo.xml	Imports Parcelable docs + reference link/attribution.
docs/xml/Android.Telephony/SignalStrengthUpdateRequest+Builder.xml	Imports builder method docs + reference links.
docs/xml/Android.Telephony/SignalStrengthUpdateRequest.xml	Imports Parcelable docs + reference link/attribution.
docs/xml/Android.Telephony/SignalStrength.xml	Imports return docs and other placeholders.
docs/xml/Android.Telephony/ServiceState.xml	Imports parameter docs and Parcelable return docs + reference links.
docs/xml/Android.Telephony/ServiceCapabilityType.xml	Imports constant summaries/remarks + reference links.
docs/xml/Android.Telephony/RadioAccessSpecifier.xml	Imports Parcelable docs, return docs, and writeToParcel docs.
docs/xml/Android.Telephony/PremiumCapability.xml	Imports premium capability constant documentation + reference link/attribution.
docs/xml/Android.Telephony/PreciseDataConnectionStateNetworkValidation.xml	Imports enum/constant summaries/remarks + reference links.
docs/xml/Android.Telephony/PhoneStateListener.xml	Imports parameter docs for callbacks.
docs/xml/Android.Telephony/PhoneState.xml	Imports enum/constant summaries/remarks + reference links.
docs/xml/Android.Telephony/PhoneNumberUtils.xml	Imports parameter and return docs for phone number utilities.
docs/xml/Android.Telephony/PhoneNumberSource.xml	Imports enum/constant summaries/remarks + reference links.
docs/xml/Android.Telephony/PhoneNumberFormattingTextWatcher.xml	Imports parameter docs and adds Android reference link.
docs/xml/Android.Telephony/PhoneNumberFormat.xml	Imports enum/constant summaries/remarks + reference links.
docs/xml/Android.Telephony/NetworkScanType.xml	Imports scan-type constant documentation + reference links.
docs/xml/Android.Telephony/NetworkScanRequest.xml	Imports Parcelable docs, return/value docs, and writeToParcel docs.
docs/xml/Android.Telephony/NetworkRegistrationInfoNrState.xml	Imports NR state constant summaries/remarks + reference links.
docs/xml/Android.Telephony/NetworkRegistrationInfoDomain.xml	Imports domain constant summaries/remarks + reference links.
docs/xml/Android.Telephony/NetworkRegistrationInfo.xml	Imports Parcelable docs + reference links.
docs/xml/Android.Telephony/NeighboringCellInfo.xml	Imports parcel constructor param docs and Parcelable return docs + reference links.
docs/xml/Android.Telephony/MultiSimMode.xml	Imports multi-SIM mode constant summaries/remarks + reference links.
docs/xml/Android.Telephony/IwlanIdType.xml	Imports IWLAN ID type constant summaries/remarks + reference links.
docs/xml/Android.Telephony/IwlanEpdgAddressType.xml	Imports ePDG address-type constant summaries/remarks + reference links.
docs/xml/Android.Telephony/IwlanEpdgAddressPreference.xml	Imports ePDG address preference constant summaries/remarks + reference links.
docs/xml/Android.Telephony/IwlanAuthenticationMethod.xml	Imports IWLAN authentication method constant summaries/remarks + reference links.
docs/xml/Android.Telephony/IncludeLocationDataType.xml	Imports include-location-data constant summaries/remarks + reference links.
docs/xml/Android.Telephony/ImsVoiceSrvccSupport.xml	Imports IMS SRVCC support constant summaries/remarks + reference links.
docs/xml/Android.Telephony/ImsVoiceSessionRefreshMethod.xml	Imports session refresh method constant summaries/remarks + reference links.
docs/xml/Android.Telephony/ImsVoiceSessionRefresherType.xml	Imports refresher type constant summaries/remarks + reference links.
docs/xml/Android.Telephony/ImsVoiceSessionPrivacyType.xml	Imports session privacy type constant summaries/remarks + reference links.
docs/xml/Android.Telephony/ImsVoicePayloadFormat.xml	Imports payload format constant summaries/remarks + reference links.
docs/xml/Android.Telephony/ImsVoiceEvsOperationalMode.xml	Imports EVS operational mode constant summaries/remarks + reference links.
docs/xml/Android.Telephony/ImsVoiceConferenceSubscribeType.xml	Imports conference subscribe type constant summaries/remarks + reference links.
docs/xml/Android.Telephony/ImsRequestUriFormat.xml	Imports request-URI format constant summaries/remarks + reference links.
docs/xml/Android.Telephony/ImsPreferredTransport.xml	Imports preferred transport constant summaries/remarks + reference links.
docs/xml/Android.Telephony/ImsNetworkType.xml	Imports IMS network-type constant summaries/remarks + reference links.
docs/xml/Android.Telephony/ImsIpsecEncryptionAlgorithm.xml	Imports IPSec encryption algorithm constant summaries/remarks + reference links.
docs/xml/Android.Telephony/ImsIpsecAuthenticationAlgorithm.xml	Imports IPSec authentication algorithm constant summaries/remarks + reference links.
docs/xml/Android.Telephony/ImsGeolocationPidfFor.xml	Imports geolocation PIDF-related constant summaries/remarks + reference links.
docs/xml/Android.Telephony/ImsEmergencyVoWifiRequires.xml	Imports VoWi-Fi emergency requirement constant summaries/remarks + reference links.
docs/xml/Android.Telephony/ImsEmergencyScanType.xml	Imports emergency scan type constant summaries/remarks + reference links.
docs/xml/Android.Telephony/ImsEmergencyDomain.xml	Imports emergency domain constant summaries/remarks + reference links.
docs/xml/Android.Telephony/IccOpenLogicalChannelResponseStatus.xml	Imports status constant summaries/remarks + reference links.
docs/xml/Android.Telephony/IccOpenLogicalChannelResponse.xml	Imports Parcelable return docs + reference link/attribution.
docs/xml/Android.Telephony/DuplexMode.xml	Imports duplex mode constant summaries/remarks + reference links.
docs/xml/Android.Telephony/DataRoamingMode.xml	Imports roaming mode constant summaries/remarks + reference links.
docs/xml/Android.Telephony/DataLimitBehavior.xml	Imports limit behavior constant summaries/remarks + reference links.
docs/xml/Android.Telephony/DataConnectionStatus.xml	Imports data connection status constant summaries/remarks + reference links.
docs/xml/Android.Telephony/D2DSharing.xml	Imports D2D sharing constant summaries/remarks + reference links.
docs/xml/Android.Telephony/ClosedSubscriberGroupInfo.xml	Imports Parcelable docs + reference links.
docs/xml/Android.Telephony/CellSignalStrengthWcdma.xml	Imports equals/hashCode/getLevel docs and Parcelable return docs + reference links.
docs/xml/Android.Telephony/CellSignalStrengthTdscdma.xml	Imports equals/hashCode/getLevel docs and writeToParcel param docs + reference links.
docs/xml/Android.Telephony/CellSignalStrengthLte.xml	Imports equals/hashCode/getLevel docs and Parcelable return docs + reference links.
docs/xml/Android.Telephony/CellSignalStrengthGsm.xml	Imports equals/hashCode/getLevel docs and Parcelable return docs + reference links.
docs/xml/Android.Telephony/CellSignalStrengthCdma.xml	Imports equals/hashCode/getLevel docs and Parcelable return docs + reference links.
docs/xml/Android.Telephony/CellSignalStrength.xml	Imports equals/hashCode/getLevel docs and adds reference links/attribution.
docs/xml/Android.Telephony/CellLocation.xml	Imports property value docs.
docs/xml/Android.Telephony/CellInfoTdscdma.xml	Imports writeToParcel param docs.
docs/xml/Android.Telephony/CellInfoNr.xml	Imports writeToParcel docs + reference link/attribution.
docs/xml/Android.Telephony/CellInfo.xml	Imports Parcelable return docs.
docs/xml/Android.Telephony/CellIdentity.xml	Imports Parcelable return docs and parceling param docs.
docs/xml/Android.Telephony/CellConnectionStatus.xml	Imports connection status constant summaries/remarks + reference links.
docs/xml/Android.Telephony/CarrierImsSmsFormat.xml	Imports IMS SMS format constant summaries/remarks + reference links.
docs/xml/Android.Telephony/BarringType.xml	Imports barring type constant summaries/remarks + reference links.
docs/xml/Android.Telephony/BarringInfo+BarringServiceInfo.xml	Imports Parcelable docs and writeToParcel docs + reference links.
docs/xml/Android.Telephony/BarringInfo.xml	Imports Parcelable docs, param docs, writeToParcel docs + reference links.
docs/xml/Android.Telephony/AvailableNetworkInfo+Builder.xml	Imports builder method docs + reference links.
docs/xml/Android.Telephony/AvailableNetworkInfo.xml	Imports value docs and Parcelable docs + reference links.
docs/xml/Android.Telephony/AutheenticationType.xml	Imports authentication-type constant summaries/remarks + reference links.
docs/xml/Android.Telephony/AccessNetworkConstants+NgranBands.xml	Imports band constant docs + reference links/attribution.
docs/xml/Android.Telephony/AccessNetworkConstants+GeranBand.xml	Imports band constant docs + reference links/attribution.
docs/xml/Android.Telephony/AccessNetworkConstants+EutranBand.xml	Imports band constant docs + reference links/attribution.
docs/xml/Android.Telephony/AccessNetworkConstants+AccessNetworkType.xml	Imports network-type constant docs + reference links/attribution.

Suppressed comments (1)

docs/xml/Android.Telephony/UiccPortInfo.xml:487

• Same mixed-content issue as above: starts with raw text (Flatten this object…) followed by children. Wrapping the leading sentence in its own keeps the XML structure consistent.

---

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

[dalexsoto]

The complete importer/output pass found five blocking data-loss or corruption paths:

• Enum-field prose, links, and attribution are emitted in <remarks>, which ECMA2Yaml ignores; this drops imported content for hundreds of fields (tools/importer.cs:630).
• Table parsing accepts headings, bare types, and empty descriptions as docs, including two TelephonyManager returns imported as Parameters instead of the NetworkScan result (tools/importer.cs:1541).
• Regex HTML stripping corrupts generic-type links and leaves )"> fragments (tools/importer.cs:1813).
• The final API section consumes page footer/trademark/"Last updated" content when no later heading exists (tools/importer.cs:1481).
• Literal \\uXXXX sequences are published instead of decoded punctuation (tools/importer.cs:689).

Please fix these importer paths and regenerate the affected XML with publishing-output validation.

[dalexsoto]

The footer, Unicode, constructor-noise, attribution-order, and mixed-remarks fixes are verified, but five blockers remain:

• Enum field prose, source links, and attribution are still emitted in <remarks> and discarded by ECMA2Yaml across the changed enum files.
• Empty table-description cells still shift columns and import bare Java types for seven return channels.
• Quote-unaware HTML stripping still leaves corrupted )\"> fragments in three APIs.
• Existing stale/incorrect source links are preserved while correct overload links are appended.
• Apply reports mark replacements as applied before successful writes, so aborted or partial batches can report changes that were never written.

Please fix these importer paths and regenerate/validate the complete output.

[jonathanpeppers]

Addressed all five blockers in fce9f94:

• Enum field prose, the exact source link, and attribution now live in <summary>, the only field consumed by ECMA2Yaml; regenerated output has 859 rendered enum summaries and zero enum source links in <remarks>.
• Android table extraction now preserves empty description cells, so seven type-only channels are skipped/restored to placeholders instead of shifting Java types into documentation.
• HTML stripping is quote-aware, including generic <...> text inside quoted link attributes; the three corrupted fragments are gone.
• Existing reference paragraphs for the same Java member anchor are replaced by the exact matched overload link, while legitimate getter/setter links remain distinct.
• Apply entries remain would_apply until each atomic write succeeds; the self-test forces a write failure and verifies it is not reported as applied.

The complete offline Android.Telephony regeneration applied 1,173 replacements across 115 files with zero errors. All changed XML parses, CRLF is preserved, the blocker quality audit is clean, and a follow-up dry-run reports zero changes.

@dalexsoto re-requesting review on the corrected head.

[jonathanpeppers]

@dalexsoto review

[dalexsoto]

The five prior importer blockers are fixed in the generated output, but two failure paths remain:

• Existing self-closing <remarks /> nodes cause the importer to append a second remarks element; ECMA2Yaml reads the original empty node and discards the imported content.
• If a later atomic write fails after earlier files succeed, per-entry statuses show applied replacements while aggregate changed-file/source counters remain zero.

Please replace/expand self-closing remarks and make partial-write reporting internally consistent, with fixtures covering both cases.

[jonathanpeppers]

Addressed both remaining failure paths in c5816db:

• Existing self-closing <remarks /> elements are now expanded in place. The fixture verifies the resulting <Docs> contains exactly one populated remarks node with the source link, so ECMA2Yaml cannot select an earlier empty node.
• Source counters are captured before writes, and filesChanged increments only after each successful atomic write. A forced two-file partial failure verifies the first file remains applied, the failed file remains would_apply, filesChanged is 1, and network/cache counters remain intact.

The complete offline Android.Telephony regeneration remains stable at 1,173 applied replacements across 115 files with zero errors. All 115 XML files parse, CRLF is preserved, there are zero duplicate remarks nodes, the prior blocker audit remains clean, and the follow-up dry-run reports zero changes.

@dalexsoto re-requesting review on the corrected head.

[jonathanpeppers]

@dalexsoto review

[dalexsoto]

The self-closing remarks and partial-write reporting fixes are verified, as are all earlier importer blockers. One independent Java-import issue remains: ExtractBlocks matches class="deprecation-block" because the current regex treats the hyphen as a word boundary, so deprecated Java APIs can import deprecation boilerplate instead of the actual documentation block. Please match the exact block class token, explicitly exclude deprecation blocks, and add deprecated type/member fixtures: tools/importer.cs.

[jonathanpeppers]

Addressed the remaining Java-import issue in 3f6a691:

• Java documentation extraction now parses each div class list, requires the exact block token, and explicitly rejects deprecation-block.
• Local Java fixtures now cover deprecation containers on both a type and a member and verify that only the actual documentation block is imported.
• Added the canonical repository guidance file .github/copilot-instructions.md, directing Android/Java documentation updates through the scoped, dry-run-first tools/importer.cs workflow.
• The importer self-test passes all 40 assertions. The complete cached Android.Telephony dry run remains idempotent with zero proposed changes and zero errors.

@dalexsoto re-requesting review on the corrected head.

[dalexsoto]

The Java deprecation-block fix, prior importer corrections, generated output, and new workflow guidance are verified. One table-selection issue remains: ExtractAndroidTableValue treats any table containing the word "Returns" as a returns table, so the RequestNetworkScan parameter table qualifies because callback prose says "Returns network scan results or errors." The parser rejects its heading and never reaches the real Returns table, leaving two authoritative NetworkScan return descriptions missing. Please match the exact Returns heading row/cell, add this fixture, and regenerate both overloads.

[jonathanpeppers]

Addressed the remaining Android table-selection issue in 94a1b36:

• Return extraction now requires a <th> cell whose normalized text exactly equals Returns; parameter prose that merely contains that word cannot select a table.
• The fixture reproduces the RequestNetworkScan layout with Returns network scan results or errors. in the callback parameter table before the real Returns table.
• Regenerated both TelephonyManager.RequestNetworkScan overloads, importing their exact official NetworkScan return descriptions.
• The importer self-test passes all 41 assertions. The changed XML parses with CRLF preserved, and the complete cached Android.Telephony dry run reports zero proposed changes and zero errors.

@dalexsoto re-requesting review on the corrected head.

[jonathanpeppers]

@dalexsoto review

[jonathanpeppers]

@dalexsoto review

[dalexsoto]

The exact Returns-heading fix and all earlier importer blockers are verified, but two issues remain:

• For 30 deprecated Android enum fields, only the first caution/deprecation paragraph is published, dropping the following substantive value description. Distinguish caution blocks from semantic prose, publish both where appropriate, add a deprecated-member fixture, and regenerate them.
• tools/importer.md uses a report path that resolves outside the repository after cd tools, while .github/copilot-instructions.md implies member-only apply although the CLI requires --path or --namespace. Align the documented paths and scope rules with actual CLI behavior.

[jonathanpeppers]

Addressed both remaining review items in bdaa682:

• Android enum summary generation now distinguishes a leading deprecation caution from following semantic value prose and publishes both as separate summary paragraphs.
• The repair path is conservative: it only refreshes an existing summary carrying both importer-style reference metadata and Android attribution, whose sole prose exactly matches the authoritative first deprecation paragraph and whose source has later semantic prose.
• Added a deprecated enum fixture covering fresh import and repair of prior caution-only generated output.
• Regenerated exactly the 30 affected enum fields across five Telephony files.
• Rewrote tools/importer.md examples to run from the repository root, so report paths resolve inside the repository.
• Clarified .github/copilot-instructions.md: apply requires --path or --namespace; --member only narrows an established write scope.

Validation: 44 self-test assertions pass; all five XML files parse with CRLF preserved; all 30 summaries contain caution plus substantive prose; the complete cached Android.Telephony dry run reports zero proposed changes and zero errors.

@dalexsoto re-requesting review on the corrected head.

[dalexsoto]

The generated output is complete, but the replacement repair path still has two blocking correctness/reporting issues:

• tools/importer.cs removes enum reference/attribution metadata before evaluating the caution-only eligibility predicate. This makes the later source check ineffective and can reconstruct non-qualifying summaries, flattening inline markup and dropping attributes. Evaluate eligibility against the untouched summary and preserve it verbatim unless the exact predicate succeeds.
• Repair-only summaries have no placeholders, so source/cache/mapping failures bypass the current reporting path near tools/importer.cs and can produce a falsely clean run. Emit a summary-targeted error/skipped entry for repair candidates with mapping.ErrorReason, and cover that failure path with a fixture.

Please fix both so the repair remains conservative and failures cannot be silently omitted.

[jonathanpeppers]

Addressed both repair-path blockers in 7bc142c:

• Repair candidates are identified from the untouched summary before any metadata cleanup: exactly one plain deprecation paragraph, importer-style reference metadata, and Android attribution.
• Repair then additionally requires the exact current source URL, exact first source paragraph, and later substantive non-deprecation prose. Any failed predicate returns the original block byte-for-byte.
• Summary opening attributes, paragraph attributes, and inline markup are preserved because eligible updates replace only summary inner content; the non-qualifying fixture verifies exact full-text equality.
• Enum remarks cleanup now runs only after an eligible summary update and is scoped to <remarks>, so it cannot mutate the summary before eligibility evaluation.
• Repair-only candidates with source/cache/mapping failures now emit a summary-targeted skipped entry with reason, detail, and source URL. The fixture covers offline_cache_miss with no placeholders.

Validation: all 48 self-test assertions pass; the complete cached Android.Telephony dry run reports zero proposed changes and zero errors; git diff --check passes. No generated XML changed.

@dalexsoto re-requesting review on the corrected head.

[dalexsoto]

The earlier repair blockers are fixed, but IsEnumSummaryRepairCandidate excludes every paragraph containing an <a> from its prose count. A summary with the expected metadata, one deprecation paragraph, and unrelated linked content can therefore qualify, after which the repair replaces the entire summary and deletes that content. Please require the untouched summary to contain exactly the importer-owned structure—the plain deprecation paragraph, exact source reference link, and exact attribution—with no additional nodes, and add a preservation fixture containing unrelated linked content.

[jonathanpeppers]

Addressed the remaining repair eligibility issue in 042c8db:

• The untouched summary must now contain exactly three <para> children in order, with only surrounding whitespace and no summary/paragraph attributes: one plain deprecation paragraph, the exact expected field reference paragraph, and exact Android attribution.
• The expected reference is derived from the field JNI registration and must match the precise URL, source label, markup, and link attributes generated by the importer.
• Any extra element, linked paragraph, comment, non-whitespace text, attribute, inline markup, wrong source, or altered attribution makes the summary ineligible and preserves it byte-for-byte.
• Added a regression fixture with unrelated linked content and asserted exact full-text preservation.

Validation: all 50 self-test assertions pass; the complete cached Android.Telephony dry run reports zero proposed changes and zero errors; git diff --check passes. No generated XML changed.

@dalexsoto re-requesting review on the corrected head.

[dalexsoto]

The enum-repair preservation fix is correct, but repository-wide importer scope still always includes docs/xml/_filter.xml, which is not an API documentation file. It reports malformed_xml, and any apply-mode error prevents all writes. Please exclude _filter.xml alongside index.xml in the path file selection and cover repository-wide scope with a regression test.

[jonathanpeppers]

Fixed in 0249a4f9.

SelectFiles now centrally excludes both root non-API XML files, docs/xml/index.xml and docs/xml/_filter.xml, for repository-wide, directory, and explicit-file path selection. The self-test now covers repository-wide enumeration and confirms exactly those two files are excluded. Documentation now records both exclusions.

Validation:

• Self-test: 52 assertions passed.
• Namespace-only repository scan: 10,367 files scanned, 0 errors; _filter.xml no longer reaches document parsing.
• Android.Telephony cached idempotence: 255 files scanned, 0 changes, 0 errors, 104 cache hits.
• git diff --check: passed.

[dalexsoto]

Root index.xml and _filter.xml are now excluded, but repository-wide --path docs/xml scans still include the three generated FrameworksIndex/*.xml files. They contain no <Docs> blocks, produce layout errors, and prevent every apply-mode write. Please exclude docs/xml/FrameworksIndex from file selection and cover a path-only repository-wide scan in the regression test.

[jonathanpeppers]

Fixed in 6c6b8992.

SelectFiles now excludes the complete generated docs/xml/FrameworksIndex subtree alongside root index.xml and _filter.xml, before any XML document processing. The regression now uses the exact path-only repository scope (--path docs/xml) and verifies all five non-API XML files are omitted. The importer guidance records the generated subtree exclusion.

Validation:

• Self-test: 52 assertions passed.
• Path-only repository dry run: 10,364 files scanned, 0 errors, 0 FrameworksIndex report entries.
• Android.Telephony cached idempotence: 255 files scanned, 0 changes, 0 errors, 104 cache hits.
• git diff --check: passed.