Skip to content

Commit

Permalink
doc: de-emphasize wrapping in napi_define_class
Browse files Browse the repository at this point in the history
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 <gabriel.schulhof@intel.com>
Co-authored-by: Rich Trott <rtrott@gmail.com>
Fixes: #36150
PR-URL: #36159
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Michael Dawson <midawson@redhat.com>
  • Loading branch information
2 people authored and BethGriggs committed Dec 10, 2020
1 parent b1a1834 commit ee77daf
Showing 1 changed file with 31 additions and 24 deletions.
55 changes: 31 additions & 24 deletions doc/api/n-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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
Expand Down

0 comments on commit ee77daf

Please sign in to comment.