[jonathanpeppers]

Related to #55

Scope and coverage

Import every safely matching official Android reference documentation channel for exactly Android.AdServices.Common, using tools/importer.cs without changing its matching rules. This is partial coverage, not completion of the namespace issue.

Baseline: fbcc13f05d93195182e95685e520f1b198504467. Across all 24 namespace type XML files and docs\xml\ns-Android.AdServices.Common.xml, true placeholder-bearing direct Docs channels decrease 357 -> 275, a net reduction of 82 (23.0%). 14 XML files change, with 225 insertions / 82 deletions.

Imported channel	Count
summary	35
remarks	29
returns	8
param	10
Total	82

These imports cover builder setters, component-ad construction and accessors, declared parcelable members, and the source-registered AdEventType.Win constant. All source references use exact official declarations, including constructor/parameter descriptors and the FrequencyCapFilters.AD_EVENT_TYPE_WIN owner for the projected enum constant. New remarks and the enum summary retain Android source references and CC BY 2.5 attribution. Existing non-placeholder documentation and API metadata remain unchanged; there is no inherited-member guess, AOSP fallback, invented prose, or manual placeholder replacement.

Changed file under docs\xml\Android.AdServices.Common	Baseline	Remaining
AdData+Builder.xml	32	22
AdData.xml	25	20
AdEventType.xml	6	5
AdFilters+Builder.xml	20	16
AdFilters.xml	22	17
AdSelectionSignals.xml	24	18
AdTechIdentifier.xml	21	15
AppInstallFilters+Builder.xml	16	14
AppInstallFilters.xml	21	16
ComponentAdData.xml	31	17
FrequencyCapFilters+Builder.xml	28	20
FrequencyCapFilters.xml	30	25
KeyedFrequencyCap+Builder.xml	27	21
KeyedFrequencyCap.xml	23	18

Remaining documentation gaps

Zero safe candidates does not mean zero placeholders. Remaining channels: 81 summaries, 78 remarks, 20 returns, 68 values, and 28 parameters.

Reason for preserving placeholder	Channels
Missing member JNI registration; no name-based guess	146
Missing type registration, including projected/helper types	18
Official text contains only a type/nullability marker or otherwise non-meaningful channel	57
Exact official declaration has no usable prose	44
Official return/value channel absent	6
Official summary absent	1
Official remarks absent	1
Namespace summary/remarks: namespace import unsupported	2
Total residuals	275

The official AppInstallFilters.Builder#setPackageNames(java.util.Set<java.lang.String>) description says “Gets the list…” even though it describes a setter. That upstream wording is preserved and explicitly flagged here, rather than replaced with invented prose. The existing missing terminal punctuation in AdData.Builder#setAdRenderId(java.lang.String) is also preserved.

Import and validation evidence

• Reviewed the full namespace-wide online dry-run (limit 5000): 82 exact structural matches, 0 errors, including both JSON/text reports and actual cached official member fragments against managed/JNI signatures.
• Applied nine separately reviewed, namespace/path-scoped offline batches: eight batches of at most 10 channels and a final batch of 2. Every apply exactly matched its reviewed dry-run identities and was followed by parsing every changed XML file and git diff --check.
• Final fresh-cache online dry-run (limit 5000): 24 type files scanned, 14 official pages fetched, 0 safe candidates / 0 errors. Its cached offline repeat also reports 0 safe candidates / 0 errors, with identical entries.
• Final importer --self-test: PASS.
• Structural audit confirms exactly the 82 reviewed placeholders changed, all existing non-placeholder Docs channels and API metadata are preserved, source links/attribution are accurate, and all 275 residual channels are accounted for. Generated index.xml, _filter.xml, FrameworksIndex, the namespace XML, and other namespaces remain untouched.
• All reports, caches, and audit scripts are kept in session artifacts outside committed files.

Reproduce the final scans from the repository root with a fresh cache outside the checkout:

dotnet run tools\importer.cs -- --self-test
$cache = Join-Path $env:TEMP 'adservices-common-doc-cache'
$report = Join-Path $env:TEMP 'adservices-common-doc-report'
dotnet run tools\importer.cs -- --path docs\xml\Android.AdServices.Common --namespace Android.AdServices.Common --max-changes 5000 --cache $cache --report "$report-online"
dotnet run tools\importer.cs -- --path docs\xml\Android.AdServices.Common --namespace Android.AdServices.Common --max-changes 5000 --cache $cache --offline --report "$report-offline"
git diff --check

The high limit above is dry-run only, not apply permission. All actual apply operations used --max-changes 10 with both the exact path and namespace scope. No closing keywords are intended; #55 must remain open for unresolved coverage.

[jonathanpeppers]

@dalexsoto review

[Copilot]

Copilot review overview

🟡 Changes recommended

The PR’s Fixes: #55 keyword would close an issue that the stated partial scope requires to remain open.

Review effort: Balanced
Findings: 1

Open (1)

• Avoid accidentally closing issue #55 via PR description · New

What changed in this PR

Imports 82 official Android documentation channels for Android.AdServices.Common while preserving unresolved placeholders.

Changes:

• Documents builder setters and component-ad APIs.
• Documents Parcelable methods and parameters.
• Documents the projected AdEventType.Win constant with attribution.

File	Description
AdData+Builder.xml	Documents five builder setters.
AdData.xml	Documents Parcelable methods.
AdEventType.xml	Documents the Win enum value.
AdFilters+Builder.xml	Documents filter setters.
AdFilters.xml	Documents Parcelable methods.
AdSelectionSignals.xml	Documents Parcelable methods.
AdTechIdentifier.xml	Documents Parcelable methods.
AppInstallFilters+Builder.xml	Documents the package-name setter.
AppInstallFilters.xml	Documents Parcelable methods.
ComponentAdData.xml	Documents construction, accessors, and Parcelable methods.
FrequencyCapFilters+Builder.xml	Documents event-specific cap setters.
FrequencyCapFilters.xml	Documents Parcelable methods.
KeyedFrequencyCap+Builder.xml	Documents frequency-cap setters.
KeyedFrequencyCap.xml	Documents Parcelable methods.

---

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

[dalexsoto]

The AdServices Common imports match their registered members and projected constant owners, preserve authored content and API metadata, and retain source references and attribution through the established member and enum publishing paths. The non-closing issue reference and explicitly acknowledged source-fidelity choices are respected; no independent blocking regression remains.