Document NfcAdapter NDEF push methods

[jonathanpeppers]

Refs #178

Sources

• Android developer reference: https://developer.android.com/reference/android/nfc/NfcAdapter
• AOSP API 28 source documentation for setNdefPushMessage: https://android.googlesource.com/platform/frameworks/base/+/android-9.0.0_r1/core/java/android/nfc/NfcAdapter.java#1083
• AOSP API 28 source documentation for setNdefPushMessageCallback: https://android.googlesource.com/platform/frameworks/base/+/android-9.0.0_r1/core/java/android/nfc/NfcAdapter.java#1196

Validation

• Parsed docs/xml/Android.Nfc/NfcAdapter.xml as XML.
• Verified CRLF-only line endings and git diff --check.
• Verified both scoped members contain no placeholders and their AOSP source anchors return HTTP 200.

[Copilot]

Pull request overview

Updates the generated XML documentation for Android.Nfc.NfcAdapter to replace placeholders with real docs for the NDEF push (“Android Beam”) APIs, improving the usefulness of the published Android API docs.

Changes:

• Filled in <param>, <summary>, and <remarks> for SetNdefPushMessage and SetNdefPushMessageCallback.
• Added AOSP source documentation links for both members.
• Added an UnsupportedOperationException entry for both members.

Suppressed comments (2)

docs/xml/Android.Nfc/NfcAdapter.xml:3101

• This file consistently documents the required permission as the Android constant (e.g. android.Manifest.permission#NFC). Using Android.Manifest.Permission.Nfc here is inconsistent with the surrounding docs and makes the permission name less recognizable to Android devs.

          <para>Requires the <c>Android.Manifest.Permission.Nfc</c> permission.</para>

docs/xml/Android.Nfc/NfcAdapter.xml:3106

• Most members in this file include a developer.android.com reference link paragraph in before the AOSP/CC BY attribution. Adding the same "Java documentation for …" link for this method would keep the docs consistent and provide a stable reference target.

          <para>
            <format type="text/html">
              <a href="https://android.googlesource.com/platform/frameworks/base/+/android-9.0.0_r1/core/java/android/nfc/NfcAdapter.java#1196" title="Android Open Source Project source">Android Open Source Project source documentation for <code>android.nfc.NfcAdapter.setNdefPushMessageCallback</code>.</a>
            </format>
          </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]

Three NDEF-push contracts remain inaccurate:

• IllegalStateException is for an already-destroyed activity, not one that is merely not resumed.
• Clearing one static/callback provider does not disable push while the other remains registered; both must be cleared.
• Android Beam was deprecated in API 29 and removed, but the docs present it as a current functional feature without warning.

Please document the actual exception condition, independent providers, and deprecation/removal.

[jonathanpeppers]

@dalexsoto Addressed all three NDEF-push contracts in e32553b: IllegalStateException now applies only to an already-destroyed activity; clearing a static message or callback now documents that it clears only that provider while the other can remain active; and both methods now state that Android Beam was deprecated in API level 29 and is unavailable on Android 10 (API level 29) or later.

[dalexsoto]

The destroyed-activity and independent-provider fixes are correct, but two blockers remain:

• Android Beam was deprecated in API 29 yet remained feature-dependent and functional through API 33; removal/no-op behavior starts in API 34, not API 29.
• Current nullable managed signatures allow null activity/array/elements, which functional implementations reject with NullPointerException; document those non-null requirements and exceptions.

Please correct the removal timeline and nullable argument contracts.

[jonathanpeppers]

Addressed the latest review in 4efb71a: Android Beam is now documented as deprecated in API 29, functional when supported through API 33, and removed/no-op starting in API 34. Both overloads now state that the managed nullable activity, activities array, and every array element must be non-null on functional implementations, with Java.Lang.NullPointerException documented for violations. XML parsing, CRLF line endings, and git diff --check all pass.

[dalexsoto]

The API 29/34 lifecycle and nullable-argument fixes are correct, but both new developer.android.com references use method fragments that no longer exist, so they land on the NfcAdapter class page instead of the cited method documentation: NfcAdapter.xml and the second overload. Please remove those links or replace them with valid historical/removal references; the AOSP links already resolve.