diff --git a/doc/api/n-api.md b/doc/api/n-api.md index d1fb432d7d416f..fe3786aaaf5a3f 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -1059,20 +1059,24 @@ napi_status napi_create_external(napi_env env, ``` - `[in] env`: The environment that the API is invoked under. -- `[in] data`: Raw pointer to the external data being wrapped. -- `[in] finalize_cb`: Optional callback to call when the wrapped object +- `[in] data`: Raw pointer to the external data. +- `[in] finalize_cb`: Optional callback to call when the external value is being collected. - `[in] finalize_hint`: Optional hint to pass to the finalize callback during collection. -- `[out] result`: A `napi_value` representing an external object. +- `[out] result`: A `napi_value` representing an external value. Returns `napi_ok` if the API succeeded. -This API allocates a JavaScript object with external data attached to it. -This is used to wrap native objects and project them into JavaScript. -The API allows the caller to pass in a finalize callback, in case the -underlying native resource needs to be cleaned up when the wrapper -JavaScript object gets collected. +This API allocates a JavaScript value with external data attached to it. This +is used to pass external data through JavaScript code, so it can be retrieved +later by native code. The API allows the caller to pass in a finalize callback, +in case the underlying native resource needs to be cleaned up when the external +JavaScript value gets collected. + +*Note*: The created value is not an object, and therefore does not support +additional properties. It is considered a distinct value type: calling +`napi_typeof()` with an external value yields `napi_external`. #### napi_create_external_arraybuffer