From f5efd54727aef6f353be78a4f8164a207280a126 Mon Sep 17 00:00:00 2001 From: Gabriel Schulhof Date: Tue, 17 Nov 2020 20:13:37 -0800 Subject: [PATCH] doc: de-emphasize wrapping in napi_define_class Change the documentation for `napi_define_class` in such a way that it mentions wrapping C++ class instances as a possible use for the API, rather than making the assumption that it is the use case for the API. Signed-off-by: Gabriel Schulhof Co-authored-by: Rich Trott Fixes: https://github.com/nodejs/node/issues/36150 PR-URL: https://github.com/nodejs/node/pull/36159 Reviewed-By: Rich Trott Reviewed-By: Michael Dawson --- doc/api/n-api.md | 55 +++++++++++++++++++++++++++--------------------- 1 file changed, 31 insertions(+), 24 deletions(-) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index aa4598877e2d90..e73bf3a06f710c 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -4720,14 +4720,15 @@ napi_status napi_define_class(napi_env env, ``` * `[in] env`: The environment that the API is invoked under. -* `[in] utf8name`: Name of the JavaScript constructor function; this is - not required to be the same as the C++ class name, though it is recommended - for clarity. +* `[in] utf8name`: Name of the JavaScript constructor function; When wrapping a + C++ class, we recommend for clarity that this name be the same as that of + the C++ class. * `[in] length`: The length of the `utf8name` in bytes, or `NAPI_AUTO_LENGTH` if it is null-terminated. * `[in] constructor`: Callback function that handles constructing instances - of the class. This should be a static method on the class, not an actual - C++ constructor function. [`napi_callback`][] provides more details. + of the class. When wrapping a C++ class, this method must be a static member + with the [`napi_callback`][] signature. A C++ class constructor cannot be + used. [`napi_callback`][] provides more details. * `[in] data`: Optional data to be passed to the constructor callback as the `data` property of the callback info. * `[in] property_count`: Number of items in the `properties` array argument. @@ -4739,27 +4740,33 @@ napi_status napi_define_class(napi_env env, Returns `napi_ok` if the API succeeded. -Defines a JavaScript class that corresponds to a C++ class, including: - -* A JavaScript constructor function that has the class name and invokes the - provided C++ constructor callback. -* Properties on the constructor function corresponding to _static_ data - properties, accessors, and methods of the C++ class (defined by - property descriptors with the `napi_static` attribute). -* Properties on the constructor function's `prototype` object corresponding to - _non-static_ data properties, accessors, and methods of the C++ class - (defined by property descriptors without the `napi_static` attribute). - -The C++ constructor callback should be a static method on the class that calls -the actual class constructor, then wraps the new C++ instance in a JavaScript -object, and returns the wrapper object. See `napi_wrap()` for details. +Defines a JavaScript class, including: + +* A JavaScript constructor function that has the class name. When wrapping a + corresponding C++ class, the callback passed via `constructor` can be used to + instantiate a new C++ class instance, which can then be placed inside the + JavaScript object instance being constructed using [`napi_wrap`][]. +* Properties on the constructor function whose implementation can call + corresponding _static_ data properties, accessors, and methods of the C++ + class (defined by property descriptors with the `napi_static` attribute). +* Properties on the constructor function's `prototype` object. When wrapping a + C++ class, _non-static_ data properties, accessors, and methods of the C++ + class can be called from the static functions given in the property + descriptors without the `napi_static` attribute after retrieving the C++ class + instance placed inside the JavaScript object instance by using + [`napi_unwrap`][]. + +When wrapping a C++ class, the C++ constructor callback passed via `constructor` +should be a static method on the class that calls the actual class constructor, +then wraps the new C++ instance in a JavaScript object, and returns the wrapper +object. See [`napi_wrap`][] for details. The JavaScript constructor function returned from [`napi_define_class`][] is -often saved and used later, to construct new instances of the class from native -code, and/or check whether provided values are instances of the class. In that -case, to prevent the function value from being garbage-collected, create a -persistent reference to it using [`napi_create_reference`][] and ensure the -reference count is kept >= 1. +often saved and used later to construct new instances of the class from native +code, and/or to check whether provided values are instances of the class. In +that case, to prevent the function value from being garbage-collected, a +strong persistent reference to it can be created using +[`napi_create_reference`][], ensuring that the reference count is kept >= 1. Any non-`NULL` data which is passed to this API via the `data` parameter or via the `data` field of the `napi_property_descriptor` array items can be associated