(cordova-ios) 01/01: chore(doc): document deprecation of `CDVPluginResult.associatedObject` with samples

[ma...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

GitToTheHub pushed a commit to branch pr-doc-deprecation-of-associatedObject
in repository https://gitbox.apache.org/repos/asf/cordova-ios.git

commit 25ebd9eca868ebcf72f794ee8a3bd0554a3fdda6
Author: Manuel Beck <ma...@outlook.de>
AuthorDate: Fri Jul 31 22:44:22 2026 +0200

    chore(doc): document deprecation of `CDVPluginResult.associatedObject` with samples
    
    - Document in plugin's upgrade guide `CordovaLib/CordovaLib.docc/upgrading-8.md`
    - Document  on `CordovaLib/include/Cordova/CDVPluginResult.h`
---
 CordovaLib/CordovaLib.docc/upgrading-8.md    | 37 ++++++++++++++++++++++++++++
 CordovaLib/include/Cordova/CDVPluginResult.h | 21 ++++++++++++++++
 2 files changed, 58 insertions(+)

diff --git a/CordovaLib/CordovaLib.docc/upgrading-8.md b/CordovaLib/CordovaLib.docc/upgrading-8.md
index c628f7ff..e84aa335 100644
--- a/CordovaLib/CordovaLib.docc/upgrading-8.md
+++ b/CordovaLib/CordovaLib.docc/upgrading-8.md
@@ -187,6 +187,43 @@ result?.setKeepCallbackAs(true)
 self.commandDelegate.send(result, callbackId: callback)
 ```
 
+### Deprecating `CDVPluginResult.associatedObject`
+
+The `associatedObject` property on ``CDVPluginResult`` is now deprecated.
+
+Historically, this was commonly used as a lifetime-retention helper for legacy
+ Objective-C patterns such as constructing a string with
+ `initWithBytesNoCopy:...`, where the created `NSString` could depend on an
+ external `NSData` buffer remaining alive.
+
+In modern plugin code, prefer APIs that do not rely on external buffer
+ lifetimes.
+
+```objc
+// Old code
+NSString* payload = [[NSString alloc] initWithBytesNoCopy:(void*)[data bytes]
+                                                   length:[data length]
+                                                 encoding:NSUTF8StringEncoding
+                                             freeWhenDone:NO];
+CDVPluginResult* result = [CDVPluginResult resultWithStatus:CDVCommandStatus_OK
+                                             messageAsString:payload];
+result.associatedObject = data;
+```
+
+```objc
+// New code
+NSString* payload = [[NSString alloc] initWithData:data
+                                           encoding:NSUTF8StringEncoding];
+CDVPluginResult* result = [CDVPluginResult resultWithStatus:CDVCommandStatus_OK
+                                             messageAsString:payload];
+```
+
+For binary payloads, prefer message constructors that accept `NSData` directly,
+ such as `resultWithStatus:messageAsArrayBuffer:`.
+
+If you must retain auxiliary state, keep it in your plugin instance until after
+ sending the result, rather than attaching it to `CDVPluginResult`.
+
 ## Other Major Changes
 ### Deprecating AppDelegate category extensions
 
diff --git a/CordovaLib/include/Cordova/CDVPluginResult.h b/CordovaLib/include/Cordova/CDVPluginResult.h
index b0b55844..abf8c09b 100644
--- a/CordovaLib/include/Cordova/CDVPluginResult.h
+++ b/CordovaLib/include/Cordova/CDVPluginResult.h
@@ -131,6 +131,27 @@ NS_ASSUME_NONNULL_BEGIN
  }
  */
 @property (nonatomic, strong) NSNumber *keepCallback;
+/**
+ Deprecated helper previously used to retain an auxiliary object for the lifetime
+ of this plugin result.
+
+ A common legacy usage was retaining an `NSData` object when constructing a
+ `NSString` with `initWithBytesNoCopy:...`, where the string depended on the
+ original byte buffer remaining valid.
+
+ Prefer APIs that do not require external lifetime management (for example,
+ `[[NSString alloc] initWithData:encoding:]` or a message constructor that
+ accepts `NSData` directly, such as
+ ``resultWithStatus:messageAsArrayBuffer:``).
+
+ If you still need to retain additional state, hold it in your plugin instance
+ until after `sendPluginResult:callbackId:` returns rather than attaching it to
+ ``CDVPluginResult``.
+
+ @Metadata {
+     @Available(Cordova, introduced: "4.5.0", deprecated: "8.0.0")
+ }
+ */
 @property (nonatomic, strong) id associatedObject CDV_DEPRECATED(8.0.0, "");
 
 - (instancetype)init;


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@cordova.apache.org
For additional commands, e-mail: commits-help@cordova.apache.org