From 282a45d04210b29e51cb3837e28c10b526a753c5 Mon Sep 17 00:00:00 2001 From: Gabriel Schulhof Date: Tue, 21 Aug 2018 13:56:56 -0400 Subject: [PATCH] doc: update wrapping-related documentation Update the N-API documentation to reflect that wrapping no longer affects the object's prototype chain. PR-URL: https://github.com/nodejs/node/pull/22363 Reviewed-By: James M Snell Reviewed-By: Luigi Pinca Reviewed-By: Colin Ihrig Reviewed-By: Minwoo Jung Reviewed-By: Ruben Bridgewater Reviewed-By: Trivikram Kamat --- doc/api/n-api.md | 20 +++++++------------- 1 file changed, 7 insertions(+), 13 deletions(-) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index 796dc4ad271ebb..c047715395d742 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -3569,8 +3569,7 @@ napi_status napi_wrap(napi_env env, - `[in] env`: The environment that the API is invoked under. - `[in] js_object`: The JavaScript object that will be the wrapper for the - native object. This object _must_ have been created from the `prototype` of - a constructor that was created using `napi_define_class()`. + native object. - `[in] native_object`: The native instance that will be wrapped in the JavaScript object. - `[in] finalize_cb`: Optional native callback that can be used to free the @@ -3602,13 +3601,9 @@ temporarily during async operations that require the instance to remain valid. *Caution*: The optional returned reference (if obtained) should be deleted via [`napi_delete_reference`][] ONLY in response to the finalize callback -invocation. (If it is deleted before then, then the finalize callback may never -be invoked.) Therefore, when obtaining a reference a finalize callback is also -required in order to enable correct proper of the reference. - -This API may modify the prototype chain of the wrapper object. Afterward, -additional manipulation of the wrapper's prototype chain may cause -`napi_unwrap()` to fail. +invocation. If it is deleted before then, then the finalize callback may never +be invoked. Therefore, when obtaining a reference a finalize callback is also +required in order to enable correct disposal of the reference. Calling `napi_wrap()` a second time on an object will return an error. To associate another native instance with the object, use `napi_remove_wrap()` @@ -3658,10 +3653,9 @@ napi_status napi_remove_wrap(napi_env env, Returns `napi_ok` if the API succeeded. Retrieves a native instance that was previously wrapped in the JavaScript -object `js_object` using `napi_wrap()` and removes the wrapping, thereby -restoring the JavaScript object's prototype chain. If a finalize callback was -associated with the wrapping, it will no longer be called when the JavaScript -object becomes garbage-collected. +object `js_object` using `napi_wrap()` and removes the wrapping. If a finalize +callback was associated with the wrapping, it will no longer be called when the +JavaScript object becomes garbage-collected. ## Simple Asynchronous Operations