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 <[email protected]>
Co-authored-by: Rich Trott <[email protected]>
Fixes: #36150
PR-URL: #36159
Reviewed-By: Rich Trott <[email protected]>
Reviewed-By: Michael Dawson <[email protected]>

Author: 2 people

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