From 4bd72c3c15bc7fb2e84fe161b484fdb011daeb1d Mon Sep 17 00:00:00 2001 From: NickNaso Date: Fri, 7 Sep 2018 21:38:06 +0200 Subject: [PATCH 1/9] Cleaning the documentation Remove comments about things under development Include Napi namespace consistently --- README.md | 15 +++-- doc/array_buffer.md | 66 ++++++++++----------- doc/async_operations.md | 2 +- doc/async_worker.md | 64 ++++++++++---------- doc/basic_types.md | 63 +++++++++----------- doc/boolean.md | 10 +--- doc/buffer.md | 64 ++++++++++---------- doc/callbackinfo.md | 29 ++++----- doc/env.md | 18 +++--- doc/error.md | 42 ++++++------- doc/error_handling.md | 57 +++++++++--------- doc/escapable_handle_scope.md | 26 ++++---- doc/external.md | 36 ++++++----- doc/function.md | 6 +- doc/function_reference.md | 4 +- doc/handle_scope.md | 19 +++--- doc/memory_management.md | 4 +- doc/number.md | 5 +- doc/object.md | 68 ++++++++++----------- doc/object_lifetime_management.md | 20 +++---- doc/object_reference.md | 22 +++---- doc/promises.md | 34 +++++------ doc/property_descriptor.md | 22 +++---- doc/range_error.md | 32 +++++----- doc/reference.md | 42 ++++++------- doc/setup.md | 2 +- doc/string.md | 8 +-- doc/symbol.md | 16 ++--- doc/type_error.md | 32 +++++----- doc/typed_array.md | 12 ++-- doc/typed_array_of.md | 52 ++++++++-------- doc/value.md | 99 ++++++++++++++++--------------- 32 files changed, 481 insertions(+), 510 deletions(-) diff --git a/README.md b/README.md index 9d4011575..cdc01fe42 100644 --- a/README.md +++ b/README.md @@ -1,19 +1,19 @@ -# **node-addon-api module** +# **node-addon-api module** This module contains **header-only C++ wrapper classes** which simplify the use of the C based [N-API](https://nodejs.org/dist/latest/docs/api/n-api.html) provided by Node.js when using C++. It provides a C++ object model and exception handling semantics with low overhead. -N-API is an ABI stable C interface provided by Node.js for building native +N-API is an ABI stable C interface provided by Node.js for building native addons. It is independent from the underlying JavaScript runtime (e.g. V8 or ChakraCore) -and is maintained as part of Node.js itself. It is intended to insulate -native addons from changes in the underlying JavaScript engine and allow -modules compiled for one version to run on later versions of Node.js without +and is maintained as part of Node.js itself. It is intended to insulate +native addons from changes in the underlying JavaScript engine and allow +modules compiled for one version to run on later versions of Node.js without recompilation. The `node-addon-api` module, which is not part of Node.js, preserves the benefits of the N-API as it consists only of inline code that depends only on the stable API -provided by N-API. As such, modules built against one version of Node.js +provided by N-API. As such, modules built against one version of Node.js using node-addon-api should run without having to be rebuilt with newer versions of Node.js. @@ -63,8 +63,7 @@ to ideas specified in the **ECMA262 Language Specification**. ### **API Documentation** -The following is the documentation for node-addon-api (NOTE: -still a work in progress as its not yet complete). +The following is the documentation for node-addon-api. - [Basic Types](doc/basic_types.md) - [Array](doc/basic_types.md#array) diff --git a/doc/array_buffer.md b/doc/array_buffer.md index 754983686..8f76b992f 100644 --- a/doc/array_buffer.md +++ b/doc/array_buffer.md @@ -1,6 +1,6 @@ # ArrayBuffer -The `ArrayBuffer` class corresponds to the +The `Napi::ArrayBuffer` class corresponds to the [JavaScript `ArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer) class. @@ -8,94 +8,94 @@ class. ### New -Allocates a new `ArrayBuffer` instance with a given length. +Allocates a new `Napi::ArrayBuffer` instance with a given length. ```cpp -static ArrayBuffer New(napi_env env, size_t byteLength); +static Napi::ArrayBuffer New(napi_env env, size_t byteLength); ``` -- `[in] env`: The environment in which to create the `ArrayBuffer` instance. +- `[in] env`: The environment in which to create the `Napi::ArrayBuffer` instance. - `[in] byteLength`: The length to be allocated, in bytes. -Returns a new `ArrayBuffer` instance. +Returns a new `Napi::ArrayBuffer` instance. ### New -Wraps the provided external data into a new `ArrayBuffer` instance. +Wraps the provided external data into a new `Napi::ArrayBuffer` instance. -The `ArrayBuffer` instance does not assume ownership for the data and expects it -to be valid for the lifetime of the instance. Since the `ArrayBuffer` is subject -to garbage collection this overload is only suitable for data which is static -and never needs to be freed. +The `Napi::ArrayBuffer` instance does not assume ownership for the data and +expects it to be valid for the lifetime of the instance. Since the +`Napi::ArrayBuffer` is subject to garbage collection this overload is only +suitable for data which is static and never needs to be freed. ```cpp -static ArrayBuffer New(napi_env env, void* externalData, size_t byteLength); +static Napi::ArrayBuffer New(napi_env env, void* externalData, size_t byteLength); ``` -- `[in] env`: The environment in which to create the `ArrayBuffer` instance. +- `[in] env`: The environment in which to create the `Napi::ArrayBuffer` instance. - `[in] externalData`: The pointer to the external data to wrap. - `[in] byteLength`: The length of the `externalData`, in bytes. -Returns a new `ArrayBuffer` instance. +Returns a new `Napi::ArrayBuffer` instance. ### New -Wraps the provided external data into a new `ArrayBuffer` instance. +Wraps the provided external data into a new `Napi::ArrayBuffer` instance. -The `ArrayBuffer` instance does not assume ownership for the data and expects it -to be valid for the lifetime of the instance. The data can only be freed once -the `finalizeCallback` is invoked to indicate that the `ArrayBuffer` has been -released. +The `Napi::ArrayBuffer` instance does not assume ownership for the data and +expects it to be valid for the lifetime of the instance. The data can only be +freed once the `finalizeCallback` is invoked to indicate that the +`Napi::ArrayBuffer` has been released. ```cpp template -static ArrayBuffer New(napi_env env, +static Napi::ArrayBuffer New(napi_env env, void* externalData, size_t byteLength, Finalizer finalizeCallback); ``` -- `[in] env`: The environment in which to create the `ArrayBuffer` instance. +- `[in] env`: The environment in which to create the `Napi::ArrayBuffer` instance. - `[in] externalData`: The pointer to the external data to wrap. - `[in] byteLength`: The length of the `externalData`, in bytes. -- `[in] finalizeCallback`: A function to be called when the `ArrayBuffer` is +- `[in] finalizeCallback`: A function to be called when the `Napi::ArrayBuffer` is destroyed. It must implement `operator()`, accept a `void*` (which is the `externalData` pointer), and return `void`. -Returns a new `ArrayBuffer` instance. +Returns a new `Napi::ArrayBuffer` instance. ### New -Wraps the provided external data into a new `ArrayBuffer` instance. +Wraps the provided external data into a new `Napi::ArrayBuffer` instance. -The `ArrayBuffer` instance does not assume ownership for the data and expects it +The `Napi::ArrayBuffer` instance does not assume ownership for the data and expects it to be valid for the lifetime of the instance. The data can only be freed once -the `finalizeCallback` is invoked to indicate that the `ArrayBuffer` has been +the `finalizeCallback` is invoked to indicate that the `Napi::ArrayBuffer` has been released. ```cpp template -static ArrayBuffer New(napi_env env, +static Napi::ArrayBuffer New(napi_env env, void* externalData, size_t byteLength, Finalizer finalizeCallback, Hint* finalizeHint); ``` -- `[in] env`: The environment in which to create the `ArrayBuffer` instance. +- `[in] env`: The environment in which to create the `Napi::ArrayBuffer` instance. - `[in] externalData`: The pointer to the external data to wrap. - `[in] byteLength`: The length of the `externalData`, in bytes. -- `[in] finalizeCallback`: The function to be called when the `ArrayBuffer` is +- `[in] finalizeCallback`: The function to be called when the `Napi::ArrayBuffer` is destroyed. It must implement `operator()`, accept a `void*` (which is the `externalData` pointer) and `Hint*`, and return `void`. - `[in] finalizeHint`: The hint to be passed as the second parameter of the finalize callback. -Returns a new `ArrayBuffer` instance. +Returns a new `Napi::ArrayBuffer` instance. ### Constructor -Initializes an empty instance of the `ArrayBuffer` class. +Initializes an empty instance of the `Napi::ArrayBuffer` class. ```cpp ArrayBuffer(); @@ -103,14 +103,14 @@ ArrayBuffer(); ### Constructor -Initializes a wrapper instance of an existing `ArrayBuffer` object. +Initializes a wrapper instance of an existing `Napi::ArrayBuffer` object. ```cpp ArrayBuffer(napi_env env, napi_value value); ``` -- `[in] env`: The environment in which to create the `ArrayBuffer` instance. -- `[in] value`: The `ArrayBuffer` reference to wrap. +- `[in] env`: The environment in which to create the `Napi::ArrayBuffer` instance. +- `[in] value`: The `Napi::ArrayBuffer` reference to wrap. ### ByteLength diff --git a/doc/async_operations.md b/doc/async_operations.md index b8dec37cf..ee445dd3f 100644 --- a/doc/async_operations.md +++ b/doc/async_operations.md @@ -17,7 +17,7 @@ Node Addon API provides an interface to support functions that cover the most common asynchronous use cases. There is an abstract classes to implement asynchronous operations: -- **[AsyncWorker](async_worker.md)** +- **[`Napi::AsyncWorker`](async_worker.md)** These class helps manage asynchronous operations through an abstraction of the concept of moving data between the **event loop** and **worker threads**. diff --git a/doc/async_worker.md b/doc/async_worker.md index 0d78c1b62..fa9d7c34e 100644 --- a/doc/async_worker.md +++ b/doc/async_worker.md @@ -1,14 +1,14 @@ # AsyncWorker -`AsyncWorker` is an abstract class that you can subclass to remove many of the +`Napi::AsyncWorker` is an abstract class that you can subclass to remove many of the tedious tasks of moving data between the event loop and worker threads. This class internally handles all the details of creating and executing an asynchronous operation. Once created, execution is requested by calling `Queue`. When a thread is available for execution the `Execute` method will be invoked. Once `Execute` -complets either `OnOK` or `OnError` will be invoked. Once the `OnOK` or -`OnError` methods are complete the AsyncWorker instance is destructed. +complets either `OnOK` or `OnError` will be invoked. Once the `OnOK` or +`OnError` methods are complete the `Napi::AsyncWorker` instance is destructed. For the most basic use, only the `Execute` method must be implemented in a subclass. @@ -20,7 +20,7 @@ subclass. Requests the environment in which the async worker has been initially created. ```cpp -Env Env() const; +Napi::Env Env() const; ``` Returns the environment in which the async worker has been created. @@ -46,7 +46,7 @@ void Cancel(); ### Receiver ```cpp -ObjectReference& Receiver(); +Napi::ObjectReference& Receiver(); ``` Returns the persistent object reference of the receiver object set when the async @@ -55,7 +55,7 @@ worker was created. ### Callback ```cpp -FunctionReference& Callback(); +Napi::FunctionReference& Callback(); ``` Returns the persistent function reference of the callback set when the async @@ -81,7 +81,7 @@ This method is used to execute some tasks out of the **event loop** on a libuv worker thread. Subclasses must implement this method and the method is run on a thread other than that running the main event loop. As the method is not running on the main event loop, it must avoid calling any methods from node-addon-api -or running any code that might invoke JavaScript. Instead once this method is +or running any code that might invoke JavaScript. Instead once this method is complete any interaction through node-addon-api with JavaScript should be implemented in the `OnOK` method which runs on the main thread and is invoked when the `Execute` method completes. @@ -114,7 +114,7 @@ virtual void OnError(const Error& e); ### Constructor -Creates a new `AsyncWorker`. +Creates a new `Napi::AsyncWorker`. ```cpp explicit AsyncWorker(const Function& callback); @@ -123,12 +123,12 @@ explicit AsyncWorker(const Function& callback); - `[in] callback`: The function which will be called when an asynchronous operations ends. The given function is called from the main event loop thread. -Returns an AsyncWork instance which can later be queued for execution by calling +Returns a`Napi::AsyncWork` instance which can later be queued for execution by calling `Queue`. ### Constructor -Creates a new `AsyncWorker`. +Creates a new `Napi::AsyncWorker`. ```cpp explicit AsyncWorker(const Function& callback, const char* resource_name); @@ -140,13 +140,12 @@ operations ends. The given function is called from the main event loop thread. identifier for the kind of resource that is being provided for diagnostic information exposed by the async_hooks API. -Returns an AsyncWork instance which can later be queued for execution by calling +Returns a `Napi::AsyncWork` instance which can later be queued for execution by calling `Queue`. - ### Constructor -Creates a new `AsyncWorker`. +Creates a new `Napi::AsyncWorker`. ```cpp explicit AsyncWorker(const Function& callback, const char* resource_name, const Object& resource); @@ -160,12 +159,12 @@ information exposed by the async_hooks API. - `[in] resource`: Object associated with the asynchronous operation that will be passed to possible async_hooks. -Returns an AsyncWork instance which can later be queued for execution by calling +Returns a `Napi::AsyncWork` instance which can later be queued for execution by calling `Queue`. ### Constructor -Creates a new `AsyncWorker`. +Creates a new `Napi::AsyncWorker`. ```cpp explicit AsyncWorker(const Object& receiver, const Function& callback); @@ -175,13 +174,12 @@ explicit AsyncWorker(const Object& receiver, const Function& callback); - `[in] callback`: The function which will be called when an asynchronous operations ends. The given function is called from the main event loop thread. -Returns an AsyncWork instance which can later be queued for execution by calling +Returns a `Napi::AsyncWork` instance which can later be queued for execution by calling `Queue`. - ### Constructor -Creates a new `AsyncWorker`. +Creates a new `Napi::AsyncWorker`. ```cpp explicit AsyncWorker(const Object& receiver, const Function& callback,const char* resource_name); @@ -194,13 +192,12 @@ operations ends. The given function is called from the main event loop thread. identifier for the kind of resource that is being provided for diagnostic information exposed by the async_hooks API. -Returns an AsyncWork instance which can later be queued for execution by calling +Returns a `Napi::AsyncWork` instance which can later be queued for execution by calling `Queue`. - ### Constructor -Creates a new `AsyncWorker`. +Creates a new `Napi::AsyncWorker`. ```cpp explicit AsyncWorker(const Object& receiver, const Function& callback, const char* resource_name, const Object& resource); @@ -215,7 +212,7 @@ information exposed by the async_hooks API. - `[in] resource`: Object associated with the asynchronous operation that will be passed to possible async_hooks. -Returns an AsyncWork instance which can later be queued for execution by calling +Returns a `Napi::AsyncWork` instance which can later be queued for execution by calling `Queue`. ### Destructor @@ -232,13 +229,13 @@ virtual ~AsyncWorker(); operator napi_async_work() const; ``` -Returns the N-API napi_async_work wrapped by the AsyncWorker object. This can be -used to mix usage of the C N-API and node-addon-api. +Returns the N-API napi_async_work wrapped by the `Napi::AsyncWorker` object. This +can be used to mix usage of the C N-API and node-addon-api. ## Example -The first step to use the `AsyncWorker` class is to create a new class that inherit -from it and implement the `Execute` abstract method. Typically input to your +The first step to use the `Napi::AsyncWorker` class is to create a new class that +inherit from it and implement the `Execute` abstract method. Typically input to your worker will be saved within class' fields generally passed in through its constructor. @@ -246,11 +243,11 @@ When the `Execute` method completes without errors the `OnOK` function callback will be invoked. In this function the results of the computation will be reassembled and returned back to the initial JavaScript context. -`AsyncWorker` ensures that all the code in the `Execute` function runs in the +`Napi::AsyncWorker` ensures that all the code in the `Execute` function runs in the background out of the **event loop** thread and at the end the `OnOK` or `OnError` function will be called and are executed as part of the event loop. -The code below show a basic example of `AsyncWorker` the implementation: +The code below show a basic example of `Napi::AsyncWorker` the implementation: ```cpp #include @@ -283,11 +280,12 @@ class EchoWorker : public AsyncWorker { ``` The `EchoWorker`'s contructor calls the base class' constructor to pass in the -callback that the `AsyncWorker` base class will store persistently. When the work -on the `Execute` method is done the `OnOk` method is called and the results return -back to JavaScript invoking the stored callback with its associated environment. +callback that the `Napi::AsyncWorker` base class will store persistently. When +the work on the `Execute` method is done the `OnOk` method is called and the +results return back to JavaScript invoking the stored callback with its +associated environment. -The following code shows an example on how to create and and use an `AsyncWorker` +The following code shows an example on how to create and and use an `Napi::AsyncWorker` ```cpp Value Echo(const CallbackInfo& info) { @@ -299,7 +297,7 @@ Value Echo(const CallbackInfo& info) { return info.Env().Undefined(); ``` -Using the implementation of an `AsyncWorker` is straight forward. You need only create +Using the implementation of a `Napi::AsyncWorker` is straight forward. You need only create a new instance and pass to its constructor the callback you want to execute when your asynchronous task ends and other data you need for your computation. Once created the only other action you have to do is to call the `Queue` method that will that will diff --git a/doc/basic_types.md b/doc/basic_types.md index 43b041dc8..893cb30ac 100644 --- a/doc/basic_types.md +++ b/doc/basic_types.md @@ -6,7 +6,7 @@ interoperate with their C++ counterparts. ## Value -Value is the base class of Node Addon API's fundamental object type hierarchy. +`Napi::Value` is the base class of Node Addon API's fundamental object type hierarchy. It represents a JavaScript value of an unknown type. It is a thin wrapper around the N-API datatype `napi_value`. Methods on this class can be used to check the JavaScript type of the underlying N-API `napi_value` and also to convert to @@ -18,18 +18,18 @@ C++ types. Value(); ``` -Used to create a Node Addon API `Value` that represents an **empty** value. +Used to create a Node Addon API `Napi::Value` that represents an **empty** value. ```cpp Value(napi_env env, napi_value value); ``` -- `[in] env` - The `napi_env` environment in which to construct the Value +- `[in] env` - The `napi_env` environment in which to construct the `Napi::Value` object. -- `[in] value` - The underlying JavaScript value that the `Value` instance +- `[in] value` - The underlying JavaScript value that the `Napi::Value` instance represents. -Returns a Node.js Addon API `Value` that represents the `napi_value` passed +Returns a Node.js Addon API `Napi::Value` that represents the `napi_value` passed in. ### Operators @@ -64,10 +64,10 @@ Returns `false` if this value strictly equals another value, or `true` otherwise #### From ```cpp template -static Value From(napi_env env, const T& value); +static Napi::Value From(napi_env env, const T& value); ``` -- `[in] env` - The `napi_env` environment in which to construct the Value object. +- `[in] env` - The `napi_env` environment in which to construct the `Napi::Value` object. - `[in] value` - The C++ type to represent in JavaScript. Returns a `Napi::Value` representing the input C++ type in JavaScript. @@ -125,7 +125,7 @@ An empty value is invalid, and most attempts to perform an operation on an empty value will result in an exception. An empty value is distinct from JavaScript `null` or `undefined`, which are valid values. -When C++ exceptions are disabled at compile time, a method with a `Value` +When C++ exceptions are disabled at compile time, a method with a `Napi::Value` return type may return an empty value to indicate a pending exception. If C++ exceptions are not being used, callers should check the result of `Env::IsExceptionPending` before attempting to use the value. @@ -159,14 +159,14 @@ bool IsBoolean() const; ``` Returns `true` if the underlying value is a JavaScript `true` or JavaScript -`false`, or `false` if the value is not a Boolean value in JavaScript. +`false`, or `false` if the value is not a `Napi::Boolean` value in JavaScript. #### IsNumber ```cpp bool IsNumber() const; ``` -Returns `true` if the underlying value is a JavaScript `Number` or `false` +Returns `true` if the underlying value is a JavaScript `Napi::Number` or `false` otherwise. #### IsString @@ -174,7 +174,7 @@ otherwise. bool IsString() const; ``` -Returns `true` if the underlying value is a JavaScript `String` or `false` +Returns `true` if the underlying value is a JavaScript `Napi::String` or `false` otherwise. #### IsSymbol @@ -182,7 +182,7 @@ otherwise. bool IsSymbol() const; ``` -Returns `true` if the underlying value is a JavaScript `Symbol` or `false` +Returns `true` if the underlying value is a JavaScript `Napi::Symbol` or `false` otherwise. #### IsArray @@ -190,7 +190,7 @@ otherwise. bool IsArray() const; ``` -Returns `true` if the underlying value is a JavaScript `Array` or `false` +Returns `true` if the underlying value is a JavaScript `Napi::Array` or `false` otherwise. #### IsArrayBuffer @@ -198,7 +198,7 @@ otherwise. bool IsArrayBuffer() const; ``` -Returns `true` if the underlying value is a JavaScript `ArrayBuffer` or `false` +Returns `true` if the underlying value is a JavaScript `Napi::ArrayBuffer` or `false` otherwise. #### IsTypedArray @@ -206,7 +206,7 @@ otherwise. bool IsTypedArray() const; ``` -Returns `true` if the underlying value is a JavaScript `TypedArray` or `false` +Returns `true` if the underlying value is a JavaScript `Napi::TypedArray` or `false` otherwise. #### IsObject @@ -214,7 +214,7 @@ otherwise. bool IsObject() const; ``` -Returns `true` if the underlying value is a JavaScript `Object` or `false` +Returns `true` if the underlying value is a JavaScript `Napi::Object` or `false` otherwise. #### IsFunction @@ -222,7 +222,7 @@ otherwise. bool IsFunction() const; ``` -Returns `true` if the underlying value is a JavaScript `Function` or `false` +Returns `true` if the underlying value is a JavaScript `Napi::Function` or `false` otherwise. #### IsPromise @@ -230,7 +230,7 @@ otherwise. bool IsPromise() const; ``` -Returns `true` if the underlying value is a JavaScript `Promise` or `false` +Returns `true` if the underlying value is a JavaScript `Napi::Promise` or `false` otherwise. #### IsDataView @@ -238,7 +238,7 @@ otherwise. bool IsDataView() const; ``` -Returns `true` if the underlying value is a JavaScript `DataView` or `false` +Returns `true` if the underlying value is a JavaScript `Napi::DataView` or `false` otherwise. #### IsBuffer @@ -246,7 +246,7 @@ otherwise. bool IsBuffer() const; ``` -Returns `true` if the underlying value is a Node.js `Buffer` or `false` +Returns `true` if the underlying value is a Node.js `Napi::Buffer` or `false` otherwise. #### IsExternal @@ -269,10 +269,9 @@ exception if the coercion fails. If C++ exceptions are not being used, callers should check the result of `Env::IsExceptionPending` before attempting to use the returned value. - #### ToNumber ```cpp -Number ToNumber() const; +Napi::Number ToNumber() const; ``` Returns a `Napi::Number` representing the `Napi::Value`. @@ -284,10 +283,9 @@ exception if the coercion fails. If C++ exceptions are not being used, callers should check the result of `Env::IsExceptionPending` before attempting to use the returned value. - #### ToString ```cpp -String ToString() const; +Napi::String ToString() const; ``` Returns a `Napi::String` representing the `Napi::Value`. @@ -298,10 +296,9 @@ JavaScript exception if the coercion fails. If C++ exceptions are not being used, callers should check the result of `Env::IsExceptionPending` before attempting to use the returned value. - #### ToObject ```cpp -Object ToObject() const; +Napi::Object ToObject() const; ``` Returns a `Napi::Object` representing the `Napi::Value`. @@ -311,12 +308,11 @@ exception if the coercion fails. If C++ exceptions are not being used, callers should check the result of `Env::IsExceptionPending` before attempting to use the returned value. - ## Name Names are JavaScript values that can be used as a property name. There are two -specialized types of names supported in Node.js Addon API- [`String`](string.md) -and [`Symbol`](symbol.md). +specialized types of names supported in Node.js Addon API [`Napi::String`](string.md) +and [`Napi::Symbol`](symbol.md). ### Methods @@ -325,7 +321,7 @@ and [`Symbol`](symbol.md). Name(); ``` -Returns an empty `Name`. +Returns an empty `Napi::Name`. ```cpp Name(napi_env env, napi_value value); @@ -333,7 +329,7 @@ Name(napi_env env, napi_value value); - `[in] env` - The environment in which to create the array. - `[in] value` - The primitive to wrap. -Returns a Name created from the JavaScript primitive. +Returns a `Napi::Name` created from the JavaScript primitive. Note: The value is not coerced to a string. @@ -354,7 +350,6 @@ If an error occurs, a `Napi::Error` will be thrown. If C++ exceptions are not being used, callers should check the result of `Env::IsExceptionPending` before attempting to use the returned value. - ```cpp Array(napi_env env, napi_value value); ``` @@ -371,7 +366,7 @@ attempting to use the returned value. #### New ```cpp -static Array New(napi_env env); +static Napi::Array New(napi_env env); ``` - `[in] env` - The environment in which to create the array. @@ -384,7 +379,7 @@ attempting to use the returned value. #### New ```cpp -static Array New(napi_env env, size_t length); +static Napi::Array New(napi_env env, size_t length); ``` - `[in] env` - The environment in which to create the array. - `[in] length` - The length of the array. diff --git a/doc/boolean.md b/doc/boolean.md index 070f21e1f..80b420ba5 100644 --- a/doc/boolean.md +++ b/doc/boolean.md @@ -1,9 +1,5 @@ # Boolean -You are reading a draft of the next documentation and it's in continuous update so -if you don't find what you need please refer to: -[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/) - # Methods ### Constructor @@ -20,14 +16,14 @@ Napi::Boolean(); returns a new empty Javascript Boolean value type. ### operator bool -Converts a Boolean value to a boolean primitive. +Converts a `Napi::Boolean` value to a boolean primitive. ```cpp operator bool() const; ``` ### Value -Converts a Boolean value to a boolean primitive. +Converts a `Napi::Boolean` value to a boolean primitive. ```cpp bool Value() const; -``` \ No newline at end of file +``` diff --git a/doc/buffer.md b/doc/buffer.md index e37f7d980..d699c1f6d 100644 --- a/doc/buffer.md +++ b/doc/buffer.md @@ -1,112 +1,112 @@ # Buffer -The `Buffer` class creates a projection of raw data that can be consumed by +The `Napi::Buffer` class creates a projection of raw data that can be consumed by script. ## Methods ### New -Allocates a new `Buffer` object with a given length. +Allocates a new `Napi::Buffer` object with a given length. ```cpp -static Buffer New(napi_env env, size_t length); +static Napi::Buffer New(napi_env env, size_t length); ``` -- `[in] env`: The environment in which to create the `Buffer` object. +- `[in] env`: The environment in which to create the `Napi::Buffer` object. - `[in] length`: The number of `T` elements to allocate. -Returns a new `Buffer` object. +Returns a new `Napi::Buffer` object. ### New -Wraps the provided external data into a new `Buffer` object. +Wraps the provided external data into a new `Napi::Buffer` object. -The `Buffer` object does not assume ownership for the data and expects it to be -valid for the lifetime of the object. Since the `Buffer` is subject to garbage +The `Napi::Buffer` object does not assume ownership for the data and expects it to be +valid for the lifetime of the object. Since the `Napi::Buffer` is subject to garbage collection this overload is only suitable for data which is static and never needs to be freed. ```cpp -static Buffer New(napi_env env, T* data, size_t length); +static Napi::Buffer New(napi_env env, T* data, size_t length); ``` -- `[in] env`: The environment in which to create the `Buffer` object. +- `[in] env`: The environment in which to create the `Napi::Buffer` object. - `[in] data`: The pointer to the external data to expose. - `[in] length`: The number of `T` elements in the external data. -Returns a new `Buffer` object. +Returns a new `Napi::Buffer` object. ### New -Wraps the provided external data into a new `Buffer` object. +Wraps the provided external data into a new `Napi::Buffer` object. -The `Buffer` object does not assume ownership for the data and expects it +The `Napi::Buffer` object does not assume ownership for the data and expects it to be valid for the lifetime of the object. The data can only be freed once the -`finalizeCallback` is invoked to indicate that the `Buffer` has been released. +`finalizeCallback` is invoked to indicate that the `Napi::Buffer` has been released. ```cpp template -static Buffer New(napi_env env, +static Napi::Buffer New(napi_env env, T* data, size_t length, Finalizer finalizeCallback); ``` -- `[in] env`: The environment in which to create the `Buffer` object. +- `[in] env`: The environment in which to create the `Napi::Buffer` object. - `[in] data`: The pointer to the external data to expose. - `[in] length`: The number of `T` elements in the external data. -- `[in] finalizeCallback`: The function to be called when the `Buffer` is +- `[in] finalizeCallback`: The function to be called when the `Napi::Buffer` is destroyed. It must implement `operator()`, accept a `T*` (which is the external data pointer), and return `void`. -Returns a new `Buffer` object. +Returns a new `Napi::Buffer` object. ### New -Wraps the provided external data into a new `Buffer` object. +Wraps the provided external data into a new `Napi::Buffer` object. -The `Buffer` object does not assume ownership for the data and expects it to be +The `Napi::Buffer` object does not assume ownership for the data and expects it to be valid for the lifetime of the object. The data can only be freed once the -`finalizeCallback` is invoked to indicate that the `Buffer` has been released. +`finalizeCallback` is invoked to indicate that the `Napi::Buffer` has been released. ```cpp template -static Buffer New(napi_env env, +static Napi::Buffer New(napi_env env, T* data, size_t length, Finalizer finalizeCallback, Hint* finalizeHint); ``` -- `[in] env`: The environment in which to create the `Buffer` object. +- `[in] env`: The environment in which to create the `Napi::Buffer` object. - `[in] data`: The pointer to the external data to expose. - `[in] length`: The number of `T` elements in the external data. -- `[in] finalizeCallback`: The function to be called when the `Buffer` is +- `[in] finalizeCallback`: The function to be called when the `Napi::Buffer` is destroyed. It must implement `operator()`, accept a `T*` (which is the external data pointer) and `Hint*`, and return `void`. - `[in] finalizeHint`: The hint to be passed as the second parameter of the finalize callback. -Returns a new `Buffer` object. +Returns a new `Napi::Buffer` object. ### Copy -Allocates a new `Buffer` object and copies the provided external data into it. +Allocates a new `Napi::Buffer` object and copies the provided external data into it. ```cpp -static Buffer Copy(napi_env env, const T* data, size_t length); +static Napi::Buffer Copy(napi_env env, const T* data, size_t length); ``` -- `[in] env`: The environment in which to create the `Buffer` object. +- `[in] env`: The environment in which to create the `Napi::Buffer` object. - `[in] data`: The pointer to the external data to copy. - `[in] length`: The number of `T` elements in the external data. -Returns a new `Buffer` object containing a copy of the data. +Returns a new `Napi::Buffer` object containing a copy of the data. ### Constructor -Initializes an empty instance of the `Buffer` class. +Initializes an empty instance of the `Napi::Buffer` class. ```cpp Buffer(); @@ -114,13 +114,13 @@ Buffer(); ### Constructor -Initializes the `Buffer` object using an existing Uint8Array. +Initializes the `Napi::Buffer` object using an existing Uint8Array. ```cpp Buffer(napi_env env, napi_value value); ``` -- `[in] env`: The environment in which to create the `Buffer` object. +- `[in] env`: The environment in which to create the `Napi::Buffer` object. - `[in] value`: The Uint8Array reference to wrap. ### Data diff --git a/doc/callbackinfo.md b/doc/callbackinfo.md index add1ea00e..d00ec3e23 100644 --- a/doc/callbackinfo.md +++ b/doc/callbackinfo.md @@ -1,14 +1,12 @@ -**WORK IN PROGRESS, NOT YET COMPLETE** - # CallbackInfo The object representing the components of the JavaScript request being made. -The CallbackInfo object is usually created and passed by the Node.js runtime or node-addon-api infrastructure. +The `Napi::CallbackInfo` object is usually created and passed by the Node.js runtime or node-addon-api infrastructure. -The CallbackInfo object contains the arguments passed by the caller. The number of arguments is returned by the `Length` method. Each individual argument can be accessed using the `operator[]` method. +The `Napi::CallbackInfo` object contains the arguments passed by the caller. The number of arguments is returned by the `Length` method. Each individual argument can be accessed using the `operator[]` method. -The `SetData` and `Data` methods are used to set and retrieve the data pointer contained in the CallbackInfo object. +The `SetData` and `Data` methods are used to set and retrieve the data pointer contained in the `Napi::CallbackInfo` object. ## Methods @@ -18,8 +16,8 @@ The `SetData` and `Data` methods are used to set and retrieve the data pointer c CallbackInfo(napi_env env, napi_callback_info info); ``` -- `[in] env`: The `napi_env` environment in which to construct the `CallbackInfo` object. -- `[in] info`: The `napi_callback_info` data structure from which to construct the `CallbackInfo` object. +- `[in] env`: The `napi_env` environment in which to construct the `Napi::CallbackInfo` object. +- `[in] info`: The `napi_callback_info` data structure from which to construct the `Napi::CallbackInfo` object. ### Env @@ -32,10 +30,10 @@ Returns the `Env` object in which the request is being made. ### NewTarget ```cpp -Value NewTarget() const; +Napi::Value NewTarget() const; ``` -Returns the `new.target` value of the constructor call. If the function that was invoked (and for which the CallbackInfo was passed) is not a constructor call, a call to `IsEmpty()` on the returned value returns true. +Returns the `new.target` value of the constructor call. If the function that was invoked (and for which the `Napi::NCallbackInfo` was passed) is not a constructor call, a call to `IsEmpty()` on the returned value returns true. ### IsConstructCall @@ -43,8 +41,7 @@ Returns the `new.target` value of the constructor call. If the function that was bool IsConstructCall() const; ``` -Returns a `bool` indicating if the function that was invoked (and for which the CallbackInfo was passed) is a constructor call. - +Returns a `bool` indicating if the function that was invoked (and for which the `Napi::CallbackInfo` was passed) is a constructor call. ### Length @@ -52,22 +49,22 @@ Returns a `bool` indicating if the function that was invoked (and for which the size_t Length() const; ``` -Returns the number of arguments passed in the CallbackInfo object. +Returns the number of arguments passed in the `Napi::CallbackInfo` object. ### operator [] ```cpp -const Value operator [](size_t index) const; +const Napi::Value operator [](size_t index) const; ``` - `[in] index`: The zero-based index of the requested argument. -Returns a `Value` object containing the requested argument. +Returns a `Napi::Value` object containing the requested argument. ### This ```cpp -Value This() const; +Napi::Value This() const; ``` Returns the JavaScript `this` value for the call @@ -86,7 +83,7 @@ Returns the data pointer for the callback. void SetData(void* data); ``` -- `[in] data`: The new data pointer to associate with this CallbackInfo object. +- `[in] data`: The new data pointer to associate with this `Napi::CallbackInfo` object. Returns `void`. diff --git a/doc/env.md b/doc/env.md index 344b8be24..1c877bb0f 100644 --- a/doc/env.md +++ b/doc/env.md @@ -1,5 +1,3 @@ -**WORK IN PROGRESS, NOT YET COMPLETE** - # Env The opaque data structure containing the environment in which the request is being run. @@ -14,7 +12,7 @@ The Env object is usually created and passed by the Node.js runtime or node-addo Env(napi_env env); ``` -- `[in] env`: The `napi_env` environment from which to construct the `Env` object. +- `[in] env`: The `napi_env` environment from which to construct the `Napi::Env` object. ### napi_env @@ -27,26 +25,26 @@ Returns the `napi_env` opaque data structure representing the environment. ### Global ```cpp -Object Global() const; +Napi::Object Global() const; ``` -Returns the `Object` representing the environment's JavaScript Global Object. +Returns the `Napi::Object` representing the environment's JavaScript Global Object. ### Undefined ```cpp -Value Undefined() const; +Napi::Value Undefined() const; ``` -Returns the `Value` representing the environment's JavaScript Undefined Object. +Returns the `Napi::Value` representing the environment's JavaScript Undefined Object. ### Null ```cpp -Value Null() const; +Napi::Value Null() const; ``` -Returns the `Value` representing the environment's JavaScript Null Object. +Returns the `Napi::Value` representing the environment's JavaScript Null Object. ### IsExceptionPending @@ -62,4 +60,4 @@ Returns a `bool` indicating if an exception is pending in the environment. Error GetAndClearPendingException(); ``` -Returns an `Error` object representing the environment's pending exception, if any. +Returns an `Napi::Error` object representing the environment's pending exception, if any. diff --git a/doc/error.md b/doc/error.md index dc5e7ea07..4ab7d2026 100644 --- a/doc/error.md +++ b/doc/error.md @@ -1,14 +1,14 @@ # Error -The **Error** class is a representation of the JavaScript Error object that is thrown +The `Napi::Error` class is a representation of the JavaScript `Error` object that is thrown when runtime errors occur. The Error object can also be used as a base object for user-defined exceptions. -The **Error** class is a persistent reference to a JavaScript error object thus -inherits its behavior from the `ObjectReference` class (for more info see: [ObjectReference](object_reference.md)). +The `Napi::Error` class is a persistent reference to a JavaScript error object thus +inherits its behavior from the `Napi::ObjectReference` class (for more info see: [`Napi::ObjectReference`](object_reference.md)). If C++ exceptions are enabled (for more info see: [Setup](setup.md)), then the -**Error** class extends `std::exception` and enables integrated +`Napi::Error` class extends `std::exception` and enables integrated error-handling for C++ exceptions and JavaScript exceptions. For more details about error handling refer to the section titled [Error handling](error_handling.md). @@ -17,41 +17,41 @@ For more details about error handling refer to the section titled [Error handlin ### New -Creates empty instance of an `Error` object for the specified environment. +Creates empty instance of an `Napi::Error` object for the specified environment. ```cpp Error::New(Napi:Env env); ``` -- `[in] Env`: The environment in which to construct the Error object. +- `[in] env`: The environment in which to construct the `Napi::Error` object. -Returns an instance of `Error` object. +Returns an instance of `Napi::Error` object. ### New -Creates instance of an `Error` object. +Creates instance of an `Napi::Error` object. ```cpp Error::New(Napi:Env env, const char* message); ``` -- `[in] Env`: The environment in which to construct the Error object. -- `[in] message`: Null-terminated string to be used as the message for the Error. +- `[in] env`: The environment in which to construct the `Napi::Error` object. +- `[in] message`: Null-terminated string to be used as the message for the `Napi::Error`. -Returns instance of an `Error` object. +Returns instance of an `Napi::Error` object. ### New -Creates instance of an `Error` object +Creates instance of an `Napi::Error` object ```cpp Error::New(Napi:Env env, const std::string& message); ``` -- `[in] Env`: The environment in which to construct the `Error` object. -- `[in] message`: Reference string to be used as the message for the `Error`. +- `[in] env`: The environment in which to construct the `Napi::Error` object. +- `[in] message`: Reference string to be used as the message for the `Napi::Error`. -Returns instance of an `Error` object. +Returns instance of an `Napi::Error` object. ### Fatal @@ -66,26 +66,26 @@ The function call does not return, the process will be terminated. ### Constructor -Creates empty instance of an `Error`. +Creates empty instance of an `Napi::Error`. ```cpp Error(); ``` -Returns an instance of `Error` object. +Returns an instance of `Napi::Error` object. ### Constructor -Initializes an `Error` instance from an existing JavaScript error object. +Initializes an `Napi::Error` instance from an existing JavaScript error object. ```cpp Error(napi_env env, napi_value value); ``` -- `[in] Env`: The environment in which to construct the Error object. -- `[in] value`: The `Error` reference to wrap. +- `[in] env`: The environment in which to construct the error object. +- `[in] value`: The `Napi::Error` reference to wrap. -Returns instance of an `Error` object. +Returns instance of an `Napi::Error` object. ### Message diff --git a/doc/error_handling.md b/doc/error_handling.md index d56281575..d5df55450 100644 --- a/doc/error_handling.md +++ b/doc/error_handling.md @@ -6,12 +6,12 @@ have to handle and dispatch it correctly. **node-addon-api** uses return values JavaScript exceptions for error handling. You can choose return values or exception handling based on the mechanism that works best for your add-on. -The **Error** is a persistent reference (for more info see: [Object reference](object_reference.md)) +The `Napi::Error` is a persistent reference (for more info see: [`Napi::ObjectReference`](object_reference.md)) to a JavaScript error object. Use of this class depends on whether C++ exceptions are enabled at compile time. If C++ exceptions are enabled (for more info see: [Setup](setup.md)), then the -**Error** class extends `std::exception` and enables integrated +`Napi::Error` class extends `std::exception` and enables integrated error-handling for C++ exceptions and JavaScript exceptions. The following sections explain the approach for each case: @@ -34,14 +34,14 @@ returning from a native method. If a node-addon-api call fails without executing any JavaScript code (for example due to an invalid argument), then node-addon-api automatically converts and throws -the error as a C++ exception of type **Error**. +the error as a C++ exception of type `Napi::Error`. If a JavaScript function called by C++ code via node-addon-api throws a JavaScript exception, then node-addon-api automatically converts and throws it as a C++ -exception of type **Error** on return from the JavaScript code to the native +exception of type `Napi:Error` on return from the JavaScript code to the native method. -If a C++ exception of type **Error** escapes from a N-API C++ callback, then +If a C++ exception of type `Napi::Error` escapes from a N-API C++ callback, then the N-API wrapper automatically converts and throws it as a JavaScript exception. On return from a native method, node-addon-api will automatically convert a pending C++ @@ -57,35 +57,35 @@ returning from a native method. ```cpp Env env = ... -throw Error::New(env, "Example exception"); +throw Napi::Error::New(env, "Example exception"); // other C++ statements // ... ``` The statements following the throw statement will not be executed. The exception -will bubble up as a C++ exception of type **Error**, until it is either caught +will bubble up as a C++ exception of type `Napi::Error`, until it is either caught while still in C++, or else automatically propagated as a JavaScript exception when returning to JavaScript. ### Propagating a N-API C++ exception ```cpp -Function jsFunctionThatThrows = someObj.As(); -Value result = jsFunctionThatThrows({ arg1, arg2 }); +Napi::Function jsFunctionThatThrows = someObj.As(); +Napi::Value result = jsFunctionThatThrows({ arg1, arg2 }); // other C++ statements // ... ``` The C++ statements following the call to the JavaScript function will not be -executed. The exception will bubble up as a C++ exception of type **Error**, +executed. The exception will bubble up as a C++ exception of type `Napi::Error`, until it is either caught while still in C++, or else automatically propagated as a JavaScript exception when returning to JavaScript. ### Handling a N-API C++ exception ```cpp -Function jsFunctionThatThrows = someObj.As(); -Value result; +Napi::Function jsFunctionThatThrows = someObj.As(); +Napi::Value result; try { result = jsFunctionThatThrows({ arg1, arg2 }); } catch (const Error& e) { @@ -101,22 +101,22 @@ exception. ## Handling Errors Without C++ Exceptions If C++ exceptions are disabled (for more info see: [Setup](setup.md)), then the -**Error** class does not extend `std::exception`. This means that any calls to +`Napi::Error` class does not extend `std::exception`. This means that any calls to node-addon-api function do not throw a C++ exceptions. Instead, it raises -_pending_ JavaScript exceptions and returns an _empty_ **Value**. +_pending_ JavaScript exceptions and returns an _empty_ `Napi::Value`. The calling code should check `env.IsExceptionPending()` before attempting to use a -returned value, and may use methods on the **Env** class +returned value, and may use methods on the `Napi::Env` class to check for, get, and clear a pending JavaScript exception (for more info see: [Env](env.md)). If the pending exception is not cleared, it will be thrown when the native code -returns to JavaScript. +returns to JavaScript. ## Examples with C++ exceptions disabled ### Throwing a JS exception ```cpp -Env env = ... -Error::New(env, "Example exception").ThrowAsJavaScriptException(); +Napi::Env env = ... +Napi::Error::New(env, "Example exception").ThrowAsJavaScriptException(); return; ``` @@ -126,28 +126,27 @@ immediately from the native callback, after performing any necessary cleanup. ### Propagating a N-API JS exception ```cpp -Env env = ... -Function jsFunctionThatThrows = someObj.As(); -Value result = jsFunctionThatThrows({ arg1, arg2 }); +Napi::Env env = ... +Napi::Function jsFunctionThatThrows = someObj.As(); +Napi::Value result = jsFunctionThatThrows({ arg1, arg2 }); if (env.IsExceptionPending()) { Error e = env.GetAndClearPendingException(); return e.Value(); } ``` -If env.IsExceptionPending() is returns true a -JavaScript exception is pending. To let the exception propagate, the code should -generally return immediately from the native callback, after performing any -necessary cleanup. +If env.IsExceptionPending() returns true a JavaScript exception is pending. To +let the exception propagate, the code should generally return immediately from +the native callback, after performing any necessary cleanup. ### Handling a N-API JS exception ```cpp -Env env = ... -Function jsFunctionThatThrows = someObj.As(); -Value result = jsFunctionThatThrows({ arg1, arg2 }); +Napi::Env env = ... +Napi::Function jsFunctionThatThrows = someObj.As(); +Napi::Value result = jsFunctionThatThrows({ arg1, arg2 }); if (env.IsExceptionPending()) { - Error e = env.GetAndClearPendingException(); + Napi::Error e = env.GetAndClearPendingException(); cerr << "Caught JavaScript exception: " + e.Message(); } ``` diff --git a/doc/escapable_handle_scope.md b/doc/escapable_handle_scope.md index 4ebd107f4..7dedb942f 100644 --- a/doc/escapable_handle_scope.md +++ b/doc/escapable_handle_scope.md @@ -1,17 +1,17 @@ # EscapableHandleScope -The EscapableHandleScope class is used to manage the lifetime of object handles +The `Napi::EscapableHandleScope` class is used to manage the lifetime of object handles which are created through the use of node-addon-api. These handles keep an object alive in the heap in order to ensure that the objects are not collected by the garbage collector while native code is using them. A handle may be created when any new node-addon-api Value or one of its subclasses is created or returned. -An EscapableHandleScope is a special type of HandleScope +The `Napi::EscapableHandleScope` is a special type of `Napi::HandleScope` which allows a single handle to be "promoted" to an outer scope. For more details refer to the section titled -(Object lifetime management)[object_lifetime_management]. +[Object lifetime management](object_lifetime_management.md). ## Methods @@ -20,25 +20,25 @@ For more details refer to the section titled Creates a new escapable handle scope. ```cpp -EscapableHandleScope EscapableHandleScope::New(Napi:Env env); +Napi::EscapableHandleScope EscapableHandleScope::New(Napi:Env env); ``` -- `[in] Env`: The environment in which to construct the EscapableHandleScope object. +- `[in] Env`: The environment in which to construct the `Napi::EscapableHandleScope` object. -Returns a new EscapableHandleScope +Returns a new `Napi::EscapableHandleScope` ### Constructor Creates a new escapable handle scope. ```cpp -EscapableHandleScope EscapableHandleScope::New(napi_env env, napi_handle_scope scope); +Napi::EscapableHandleScope EscapableHandleScope::New(napi_env env, napi_handle_scope scope); ``` - `[in] env`: napi_env in which the scope passed in was created. - `[in] scope`: pre-existing napi_handle_scope. -Returns a new EscapableHandleScope instance which wraps the +Returns a new `Napi::EscapableHandleScope` instance which wraps the napi_escapable_handle_scope handle passed in. This can be used to mix usage of the C N-API and node-addon-api. @@ -48,7 +48,7 @@ operator EscapableHandleScope::napi_escapable_handle_scope operator EscapableHandleScope::napi_escapable_handle_scope() const ``` -Returns the N-API napi_escapable_handle_scope wrapped by the EscapableHandleScope object. +Returns the N-API napi_escapable_handle_scope wrapped by the `Napi::EscapableHandleScope` object. This can be used to mix usage of the C N-API and node-addon-api by allowing the class to be used be converted to a napi_escapable_handle_scope. @@ -57,7 +57,7 @@ the class to be used be converted to a napi_escapable_handle_scope. ~EscapableHandleScope(); ``` -Deletes the EscapableHandleScope instance and allows any objects/handles created +Deletes the `Napi::EscapableHandleScope` instance and allows any objects/handles created in the scope to be collected by the garbage collector. There is no guarantee as to when the gargbage collector will do this. @@ -69,8 +69,8 @@ napi::Value EscapableHandleScope::Escape(napi_value escapee); - `[in] escapee`: Napi::Value or napi_env to promote to the outer scope -Returns Napi:Value which can be used in the outer scope. This method can -be called at most once on a given EscapableHandleScope. If it is called +Returns `Napi::Value` which can be used in the outer scope. This method can +be called at most once on a given `Napi::EscapableHandleScope`. If it is called more than once an exception will be thrown. ### Env @@ -79,4 +79,4 @@ more than once an exception will be thrown. Napi::Env Env() const; ``` -Returns the Napi:Env associated with the EscapableHandleScope. +Returns the `Napi:Env` associated with the `Napi::EscapableHandleScope`. diff --git a/doc/external.md b/doc/external.md index 3bcda8fda..14139aa85 100644 --- a/doc/external.md +++ b/doc/external.md @@ -1,10 +1,8 @@ -**WORK IN PROGRESS, NOT YET COMPLETE** - # External (template) -The External template class implements the ability to create a Value object with arbitrary C++ data. It is the user's responsibility to manage the memory for the arbitrary C++ data. +The `Napi::External` template class implements the ability to create a `Napi::Value` object with arbitrary C++ data. It is the user's responsibility to manage the memory for the arbitrary C++ data. -External objects can be created with an optional Finalizer function and optional Hint value. The Finalizer function, if specified, is called when your External object is released by Node's garbage collector. It gives your code the opportunity to free any dynamically created data. If you specify a Hint value, it is passed to your Finalizer function. +`Napi::External` objects can be created with an optional Finalizer function and optional Hint value. The Finalizer function, if specified, is called when your `Napi::External` object is released by Node's garbage collector. It gives your code the opportunity to free any dynamically created data. If you specify a Hint value, it is passed to your Finalizer function. ## Methods @@ -12,45 +10,45 @@ External objects can be created with an optional Finalizer function and optional ```cpp template -static External New(napi_env env, T* data); +static Napi::External New(napi_env env, T* data); ``` -- `[in] env`: The `napi_env` environment in which to construct the External object. -- `[in] data`: The arbitrary C++ data to be held by the External object. +- `[in] env`: The `napi_env` environment in which to construct the `Napi::External` object. +- `[in] data`: The arbitrary C++ data to be held by the `Napi::External` object. -Returns the created `External` object. +Returns the created `Napi::External` object. ### New ```cpp template -static External New(napi_env env, +static Napi::External New(napi_env env, T* data, Finalizer finalizeCallback); ``` -- `[in] env`: The `napi_env` environment in which to construct the External object. -- `[in] data`: The arbitrary C++ data to be held by the External object. -- `[in] finalizeCallback`: A function called when the External object is released by the garbage collector accepting a T* and returning void. +- `[in] env`: The `napi_env` environment in which to construct the `Napi::External` object. +- `[in] data`: The arbitrary C++ data to be held by the `Napi::External` object. +- `[in] finalizeCallback`: A function called when the `Napi::External` object is released by the garbage collector accepting a T* and returning void. -Returns the created `External` object. +Returns the created `Napi::External` object. ### New ```cpp template -static External New(napi_env env, +static Napi::External New(napi_env env, T* data, Finalizer finalizeCallback, Hint* finalizeHint); ``` -- `[in] env`: The `napi_env` environment in which to construct the External object. -- `[in] data`: The arbitrary C++ data to be held by the External object. -- `[in] finalizeCallback`: A function called when the External object is released by the garbage collector accepting T* and Hint* parameters and returning void. +- `[in] env`: The `napi_env` environment in which to construct the `Napi::External` object. +- `[in] data`: The arbitrary C++ data to be held by the `Napi::External` object. +- `[in] finalizeCallback`: A function called when the `Napi::External` object is released by the garbage collector accepting T* and Hint* parameters and returning void. - `[in] finalizeHint`: A hint value passed to the `finalizeCallback` function. -Returns the created `External` object. +Returns the created `Napi::External` object. ### Data @@ -58,4 +56,4 @@ Returns the created `External` object. T* Data() const; ``` -Returns a pointer to the arbitrary C++ data held by the External object. +Returns a pointer to the arbitrary C++ data held by the `Napi::External` object. diff --git a/doc/function.md b/doc/function.md index ca85ef05a..22d0b71a6 100644 --- a/doc/function.md +++ b/doc/function.md @@ -5,7 +5,7 @@ native code that can later be called from JavaScript. The created function is no automatically visible from JavaScript. Instead it needs to be part of the add-on's module exports or be returned by one of the module's exported functions. -In addition the `Function` class also provides methods that can be used to call +In addition the `Napi::Function` class also provides methods that can be used to call functions that were created in JavaScript and passed to the native add-on. The `Napi::Function` class inherits its behavior from the `Napi::Object` class (for more info @@ -76,7 +76,7 @@ Creates an instance of a `Napi::Function` object. ```cpp template -static Function New(napi_env env, Callable cb, const char* utf8name = nullptr, void* data = nullptr); +static Napi::Function New(napi_env env, Callable cb, const char* utf8name = nullptr, void* data = nullptr); ``` - `[in] env`: The `napi_env` environment in which to construct the `Napi::Function` object. @@ -91,7 +91,7 @@ Returns an instance of a `Napi::Function` object. ```cpp template -static Function New(napi_env env, Callable cb, const std::string& utf8name, void* data = nullptr); +static Napi::Function New(napi_env env, Callable cb, const std::string& utf8name, void* data = nullptr); ``` - `[in] env`: The `napi_env` environment in which to construct the `Napi::Function` object. diff --git a/doc/function_reference.md b/doc/function_reference.md index e555f8b04..1462aefc8 100644 --- a/doc/function_reference.md +++ b/doc/function_reference.md @@ -23,7 +23,7 @@ Creates a "weak" reference to the value, in that the initial reference count is set to 0. ```cpp -static FunctionReference Weak(const Function& value); +static Napi::FunctionReference Weak(const Function& value); ``` - `[in] value`: The value which is to be referenced. @@ -36,7 +36,7 @@ Creates a "persistent" reference to the value, in that the initial reference count is set to 1. ```cpp -static FunctionReference Persistent(const Function& value); +static Napi::FunctionReference Persistent(const Function& value); ``` - `[in] value`: The value which is to be referenced. diff --git a/doc/handle_scope.md b/doc/handle_scope.md index 81a63fa28..a410d515f 100644 --- a/doc/handle_scope.md +++ b/doc/handle_scope.md @@ -6,7 +6,7 @@ keep an object alive in the heap in order to ensure that the objects are not collected while native code is using them. A handle may be created when any new node-addon-api Value or one of its subclasses is created or returned. For more details refer to -the section titled (Object lifetime management)[object_lifetime_management]. +the section titled [Object lifetime management](object_lifetime_management.md). ## Methods @@ -18,10 +18,9 @@ Creates a new handle scope on the stack. HandleScope(Napi:Env env); ``` -- `[in] env`: The environment in which to construct the HandleScope object. - -Returns a new HandleScope +- `[in] env`: The environment in which to construct the `Napi::HandleScope` object. +Returns a new `Napi::HandleScope` ### Constructor @@ -31,10 +30,10 @@ Creates a new handle scope on the stack. HandleScope(Napi::Env env, Napi::HandleScope scope); ``` -- `[in] env`: Napi::Env in which the scope passed in was created. -- `[in] scope`: pre-existing Napi::HandleScope. +- `[in] env`: `Napi::Env` in which the scope passed in was created. +- `[in] scope`: pre-existing `Napi::HandleScope`. -Returns a new HandleScope instance which wraps the napi_handle_scope +Returns a new `Napi::HandleScope` instance which wraps the napi_handle_scope handle passed in. This can be used to mix usage of the C N-API and node-addon-api. @@ -44,7 +43,7 @@ operator HandleScope::napi_handle_scope operator napi_handle_scope() const ``` -Returns the N-API napi_handle_scope wrapped by the EscapableHandleScope object. +Returns the N-API napi_handle_scope wrapped by the `Napi::EscapableHandleScope` object. This can be used to mix usage of the C N-API and node-addon-api by allowing the class to be used be converted to a napi_handle_scope. @@ -53,7 +52,7 @@ the class to be used be converted to a napi_handle_scope. ~HandleScope(); ``` -Deletes the HandleScope instance and allows any objects/handles created +Deletes the `Napi::HandleScope` instance and allows any objects/handles created in the scope to be collected by the garbage collector. There is no guarantee as to when the gargbage collector will do this. @@ -63,4 +62,4 @@ guarantee as to when the gargbage collector will do this. Napi::Env Env() const; ``` -Returns the Napi:Env associated with the HandleScope. +Returns the `Napi:Env` associated with the `Napi::HandleScope`. diff --git a/doc/memory_management.md b/doc/memory_management.md index 2cabd57ca..afa622550 100644 --- a/doc/memory_management.md +++ b/doc/memory_management.md @@ -1,6 +1,6 @@ # MemoryManagement -The `MemoryManagement` class contains functions that give the JavaScript engine +The `Napi::MemoryManagement` class contains functions that give the JavaScript engine an indication of the amount of externally allocated memory that is kept alive by JavaScript objects. @@ -17,7 +17,7 @@ more often than it would otherwise in an attempt to garbage collect the JavaScri objects that keep the externally allocated memory alive. ```cpp -static int64_t MemoryManagement::AdjustExternalMemory(Env env, int64_t change_in_bytes); +static int64_t Napi::MemoryManagement::AdjustExternalMemory(Napi::Env env, int64_t change_in_bytes); ``` - `[in] env`: The environment in which the API is invoked under. diff --git a/doc/number.md b/doc/number.md index a08b0abc4..0d01b26b5 100644 --- a/doc/number.md +++ b/doc/number.md @@ -3,7 +3,6 @@ A Javascript number value. ## Methods - ### Constructor ```cpp @@ -27,7 +26,7 @@ You can easily cast a Javascript number to one of: The following shows an example of casting a number to an uint32_t value. ```cpp -uint32_t operatorVal = Number::New(Env(), 10.0); // Number to unsigned 32 bit integer +uint32_t operatorVal = Napi::Number::New(Env(), 10.0); // Number to unsigned 32 bit integer // or -auto instanceVal = info[0].As().Uint32Value(); +auto instanceVal = info[0].As().Uint32Value(); ``` diff --git a/doc/object.md b/doc/object.md index 38895a10b..5be58c499 100644 --- a/doc/object.md +++ b/doc/object.md @@ -1,12 +1,12 @@ # Object -The Object class corresponds to a JavaScript object. It is extended by the following node-addon-api classes that you may use when working with more specific types: +The `Napi::Object` class corresponds to a JavaScript object. It is extended by the following node-addon-api classes that you may use when working with more specific types: -- [Value](value.md) and extends [Array](array.md) -- [ArrayBuffer](array_buffer.md) -- [Buffer](buffer.md) -- [Function](function.md) -- [TypedArray](typed_array.md). +- [`Napi::Value`](value.md) and extends [`Napi::Array`](array.md) +- [`Napi::ArrayBuffer`](array_buffer.md) +- [`Napi::Buffer`](buffer.md) +- [`Napi::Function`](function.md) +- [`Napi::TypedArray`](typed_array.md). This class provides a number of convenience methods, most of which are used to set or get properties on a JavaScript object. For example, Set() and Get(). @@ -62,19 +62,19 @@ Napi::Object::Object(napi_env env, napi_value value); - const char16_t* (encoded using UTF-16-LE, null-terminated) - std::string (encoded using UTF-8) - std::u16string - - napi::Value + - Napi::Value - napi_value -Creates a non-empty Object instance. +Creates a non-empty `Napi::Object` instance. ### New() ```cpp -Object Napi::Object::New(napi_env env); +Napi::Object Napi::Object::New(napi_env env); ``` -- `[in] env`: The `napi_env` environment in which to construct the Value object. +- `[in] env`: The `napi_env` environment in which to construct the `Napi::Value` object. -Creates a new Object value. +Creates a new `Napi::Object` value. ### Set() @@ -88,14 +88,14 @@ Add a property with the specified key with the specified value to the object. The key can be any of the following types: - `napi_value` -- [Value](value.md) +- [`Napi::Value`](value.md) - `const char*` - `const std::string&` - `uint32_t` While the value must be any of the following types: - `napi_value` -- [Value](value.md) +- [`Napi::Value`](value.md) - `const char*` - `std::string&` - `bool` @@ -104,15 +104,15 @@ While the value must be any of the following types: ### Get() ```cpp -Value Napi::Object::Get(____ key); +Napi::Value Napi::Object::Get(____ key); ``` - `[in] key`: The name of the property to return the value for. -Returns the [Value](value.md) associated with the key property. Returns NULL if no such key exists. +Returns the [`Napi::Value`](value.md) associated with the key property. Returns NULL if no such key exists. The `key` can be any of the following types: - `napi_value` -- [Value](value.md) +- [`Napi::Value`](value.md) - `const char *` - `const std::string &` - `uint32_t` @@ -131,9 +131,9 @@ Returns a `bool` that is *true* if the object has a property named `key` and *fa ```cpp bool Napi::Object::InstanceOf (const Function& constructor) const ``` -- `[in] constructor`: The constructor [Function](function.md) of the value that is being compared with the object. +- `[in] constructor`: The constructor [`Napi::Function`](function.md) of the value that is being compared with the object. -Returns a `bool` that is true if the Object is an instance created by the `constructor` and false otherwise. +Returns a `bool` that is true if the `Napi::Object` is an instance created by the `constructor` and false otherwise. Note: This is equivalent to the JavaScript instanceof operator. @@ -142,7 +142,7 @@ Note: This is equivalent to the JavaScript instanceof operator. ```cpp void Napi::Object::DefineProperty (const PropertyDescriptor& property); ``` -- `[in] property`: A [PropertyDescriptor](propertydescriptor.md). +- `[in] property`: A [`Napi::PropertyDescriptor`](propertydescriptor.md). Define a property on the object. @@ -151,52 +151,52 @@ Define a property on the object. ```cpp void Napi::Object::DefineProperties (____ properties) ``` -- `[in] properties`: A list of [PropertyDescriptor](propertydescriptor.md). Can be one of the following types: - - const std::initializer_list& - - const std::vector& +- `[in] properties`: A list of [`Napi::PropertyDescriptor`](propertydescriptor.md). Can be one of the following types: + - const std::initializer_list& + - const std::vector& Defines properties on the object. ### Operator[]() ```cpp -PropertyLValue Napi::Object::operator[] (const char* utf8name); +Napi::PropertyLValue Napi::Object::operator[] (const char* utf8name); ``` - `[in] utf8name`: UTF-8 encoded null-terminated property name. -Returns a [PropertyLValue](propertylvalue.md) as the named property or sets the named property. +Returns a [`Napi::PropertyLValue`](propertylvalue.md) as the named property or sets the named property. ```cpp -PropertyLValue Napi::Object::operator[] (const std::string& utf8name); +Napi::PropertyLValue Napi::Object::operator[] (const std::string& utf8name); ``` - `[in] utf8name`: UTF-8 encoded property name. -Returns a [PropertyLValue](propertylvalue.md) as the named property or sets the named property. +Returns a [`Napi::PropertyLValue`](propertylvalue.md) as the named property or sets the named property. ```cpp -PropertyLValue Napi::Object::operator[] (uint32_t index); +Napi::PropertyLValue Napi::Object::operator[] (uint32_t index); ``` - `[in] index`: Element index. -Returns a [PropertyLValue](propertylvalue.md) or sets an indexed property or array element. +Returns a [`Napi::PropertyLValue`](propertylvalue.md) or sets an indexed property or array element. ```cpp -Value Napi::Object::operator[] (const char* utf8name) const; +Napi::Value Napi::Object::operator[] (const char* utf8name) const; ``` - `[in] utf8name`: UTF-8 encoded null-terminated property name. -Returns the named property as a [Value](value.md). +Returns the named property as a [`Napi::Value`](value.md). ```cpp -Value Napi::Object::operator[] (const std::string& utf8name) const; +Napi::Value Napi::Object::operator[] (const std::string& utf8name) const; ``` - `[in] utf8name`: UTF-8 encoded property name. -Returns the named property as a [Value](value.md). +Returns the named property as a [`Napi::Value`](value.md). ```cpp -Value Napi::Object::operator[] (uint32_t index) const; +Napi::Value Napi::Object::operator[] (uint32_t index) const; ``` - `[in] index`: Element index. -Returns an indexed property or array element as a [Value](value.md). +Returns an indexed property or array element as a [`Napi::Value`](value.md). diff --git a/doc/object_lifetime_management.md b/doc/object_lifetime_management.md index 5c7a66c28..4ab19ecd1 100644 --- a/doc/object_lifetime_management.md +++ b/doc/object_lifetime_management.md @@ -34,7 +34,7 @@ with each of the values, one at a time: ```C++ for (int i = 0; i < LOOP_MAX; i++) { std::string name = std::string("inner-scope") + std::to_string(i); - Value newValue = String::New(info.Env(), name.c_str()); + Napi::Value newValue = Napi::String::New(info.Env(), name.c_str()); // do something with newValue }; ``` @@ -47,8 +47,8 @@ values would also be kept alive since they all share the same scope. To handle this case, node-addon-api provides the ability to establish a new 'scope' to which newly created handles will be associated. Once those handles are no longer required, the scope can be deleted and any handles -associated with the scope are invalidated. The `HandleScope` -and `EscapableHandleScope` classes are provided by node-addon-api for +associated with the scope are invalidated. The `Napi::HandleScope` +and `Napi::EscapableHandleScope` classes are provided by node-addon-api for creating additional scopes. node-addon-api only supports a single nested hierarchy of scopes. There is @@ -56,28 +56,28 @@ only one active scope at any time, and all new handles will be associated with that scope while it is active. Scopes must be deleted in the reverse order from which they are opened. In addition, all scopes created within a native method must be deleted before returning from that method. Since -HandleScopes are typically stack allocated the compiler will take care of +`Napi::HandleScopes` are typically stack allocated the compiler will take care of deletion, however, care must be taken to create the scope in the right place such that you achieve the desired lifetime. -Taking the earlier example, creating a HandleScope in the innner loop +Taking the earlier example, creating a `Napi::HandleScope` in the innner loop would ensure that at most a single new value is held alive throughout the execution of the loop: ```C for (int i = 0; i < LOOP_MAX; i++) { - HandleScope scope(info.Env()); + Napi::HandleScope scope(info.Env()); std::string name = std::string("inner-scope") + std::to_string(i); - Value newValue = String::New(info.Env(), name.c_str()); + Napi::Value newValue = Napi::String::New(info.Env(), name.c_str()); // do something with neValue }; ``` When nesting scopes, there are cases where a handle from an inner scope needs to live beyond the lifespan of that scope. node-addon-api -provides the `EscapableHandleScope` with the Escape method +provides the `Napi::EscapableHandleScope` with the `Escape` method in order to support this case. An escapable scope allows one object to be 'promoted' so that it 'escapes' the current scope and the lifespan of the handle changes from the current -scope to that of the outer scope. The Escape method can only be called -once for a given EscapableHandleScope. +scope to that of the outer scope. The `Escape` method can only be called +once for a given `Napi::EscapableHandleScope`. diff --git a/doc/object_reference.md b/doc/object_reference.md index da826f109..fd8c38f6b 100644 --- a/doc/object_reference.md +++ b/doc/object_reference.md @@ -1,8 +1,8 @@ # Object Reference -ObjectReference is a subclass of [Reference](reference.md), and is equivalent to an instance of `Reference`. This means that an ObjectReference holds an [Object](object.md), and a count of the number of references to that Object. When the count is greater than 0, an ObjectReference is not eligible for garbage collection. This ensures that the Object being held as a value of the ObjectReference will remain accessible, even if the original Object no longer is. However, ObjectReference is unique from a Reference since properties can be set and get to the Object itself that can be accessed through the ObjectReference. +`Napi::ObjectReference` is a subclass of [`Napi::Reference`](reference.md), and is equivalent to an instance of `Napi::Reference`. This means that a `Napi::ObjectReference` holds a [`Napi::Object`](object.md), and a count of the number of references to that Object. When the count is greater than 0, an ObjectReference is not eligible for garbage collection. This ensures that the Object being held as a value of the ObjectReference will remain accessible, even if the original Object no longer is. However, ObjectReference is unique from a Reference since properties can be set and get to the Object itself that can be accessed through the ObjectReference. -For more general information on references, please consult [Reference](referenc.md). +For more general information on references, please consult [`Napi::Reference`](referenc.md). ## Example ```cpp @@ -30,17 +30,17 @@ void Init(Env env) { ### Initialization ```cpp -static ObjectReference New(const Object& value, uint32_t initialRefcount = 0); +static Napi::ObjectReference New(const Object& value, uint32_t initialRefcount = 0); ``` -* `[in] value`: The Object which is to be referenced. +* `[in] value`: The `Napi::Object` which is to be referenced. * `[in] initialRefcount`: The initial reference count. Returns the newly created reference. ```cpp -static ObjectReference Weak(const Object& value); +static Napi::ObjectReference Weak(const Object& value); ``` Creates a "weak" reference to the value, in that the initial count of number of references is set to 0. @@ -50,7 +50,7 @@ Creates a "weak" reference to the value, in that the initial count of number of Returns the newly created reference. ```cpp -static ObjectReference Persistent(const Object& value); +static Napi::ObjectReference Persistent(const Object& value); ``` Creates a "persistent" reference to the value, in that the initial count of number of references is set to 1. @@ -65,7 +65,7 @@ Returns the newly created reference. ObjectReference(); ``` -Returns a new _empty_ ObjectReference instance. +Returns a new _empty_ `Napi::ObjectReference` instance. ### Constructor @@ -73,9 +73,9 @@ Returns a new _empty_ ObjectReference instance. ObjectReference(napi_env env, napi_value value); ``` -* `[in] env`: The `napi_env` environment in which to construct the ObjectReference object. +* `[in] env`: The `napi_env` environment in which to construct the `Napi::ObjectReference` object. -* `[in] value`: The N-API primitive value to be held by the ObjectReference. +* `[in] value`: The N-API primitive value to be held by the `Napi::ObjectReference`. Returns the newly created reference. @@ -103,12 +103,12 @@ The `value` can be any of the following types: ### Get ```cpp -Value Get(___ key); +Napi::Value Get(___ key); ``` * `[in] key`: The name of the property to return the value for. -Returns the [Value](value.md) associated with the key property. Returns NULL if no such key exists. +Returns the [`Napi::Value`](value.md) associated with the key property. Returns NULL if no such key exists. The `key` can be any of the following types: - `const char*` diff --git a/doc/promises.md b/doc/promises.md index e67483bbb..c08b64a1a 100644 --- a/doc/promises.md +++ b/doc/promises.md @@ -1,23 +1,19 @@ -You are reading a draft of the next documentation and it's in continuous update so -if you don't find what you need please refer to: -[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/) - # Promise -The Promise class, along with its Promise::Deferred class, implement the ability to create, resolve, and reject Promise objects. +The `Napi::Promise` class, along with its `Napi::Promise::Deferred` class, implement the ability to create, resolve, and reject `Promise` objects. -The basic approach is to create a Promise::Deferred object and return to your caller the value returned by the Promise::Deferred::Promise method. For example: +The basic approach is to create a `Napi::Promise::Deferred` object and return to your caller the value returned by the `Napi::Promise::Deferred::Promise` method. For example: ```cpp -Value YourFunction(const CallbackInfo& info) { +Napi::Value YourFunction(const Napi::CallbackInfo& info) { // your code goes here... - Promise::Deferred deferred = Promise::Deferred::New(info.Env()); + Napi::Promise::Deferred deferred = Napi::Promise::Deferred::New(info.Env()); // deferred needs to survive this call... return deferred.Promise(); } ``` -Later, when the asynchronous process completes, call either the `Resolve` or `Reject` method on the Promise::Deferred object created earlier: +Later, when the asynchronous process completes, call either the `Resolve` or `Reject` method on the `Napi::Promise::Deferred` object created earlier: ```cpp deferred.Resolve(String::New(info.Env(), "OK")); @@ -28,10 +24,10 @@ Later, when the asynchronous process completes, call either the `Resolve` or `Re ### Factory Method ```cpp -static Promise::Deferred Promise::Deferred::New(napi_env env); +static Napi::Promise::Deferred Promise::Deferred::New(napi_env env); ``` -* `[in] env`: The `napi_env` environment in which to create the Deferred object. +* `[in] env`: The `napi_env` environment in which to create the `Napi::Promise::Deferred` object. ### Constructor @@ -39,7 +35,7 @@ static Promise::Deferred Promise::Deferred::New(napi_env env); Promise::Deferred(napi_env env); ``` -* `[in] env`: The `napi_env` environment in which to construct the Deferred object. +* `[in] env`: The `napi_env` environment in which to construct the `Napi::Promise::Deferred` object. ### Env @@ -47,15 +43,15 @@ Promise::Deferred(napi_env env); Napi::Env Env() const; ``` -Returns the Env environment this Promise::Deferred object is associated with. +Returns the Env environment this `Napi::Promise::Deferred` object is associated with. ### Promise ```cpp -Promise Promise::Deferred::Promise() const; +Napi::Promise Promise::Deferred::Promise() const; ``` -Returns the Promise object held by the Promise::Deferred object. +Returns the `Napi::Promise` object held by the `Napi::Promise::Deferred` object. ### Resolve @@ -63,9 +59,9 @@ Returns the Promise object held by the Promise::Deferred object. void Promise::Deferred::Resolve(napi_value value) const; ``` -Resolves the Promise object held by the Promise::Deferred object. +Resolves the `Napi::Promise` object held by the `Napi::Promise::Deferred` object. -* `[in] value`: The N-API primitive value with which to resolve the Promise. +* `[in] value`: The N-API primitive value with which to resolve the `Napi::Promise`. ### Reject @@ -73,6 +69,6 @@ Resolves the Promise object held by the Promise::Deferred object. void Promise::Deferred::Reject(napi_value value) const; ``` -Rejects the Promise object held by the Promise::Deferred object. +Rejects the Promise object held by the `Napi::Promise::Deferred` object. -* `[in] value`: The N-API primitive value with which to reject the Promise. +* `[in] value`: The N-API primitive value with which to reject the `Napi::Promise`. diff --git a/doc/property_descriptor.md b/doc/property_descriptor.md index 02c022fcb..0f7dc8eee 100644 --- a/doc/property_descriptor.md +++ b/doc/property_descriptor.md @@ -1,6 +1,6 @@ # Property Descriptor -An [Object](object.md) can be assigned properites via its [DefineProperty](object.md#defineproperty) and [DefineProperties](object.md#defineproperties) function, which take PropertyDescrptor(s) as their parameters. The PropertyDescriptor can contain either values or functions, which are then assigned to the Object. Note that a single instance of a PropertyDescriptor class can only contain either one value, or at most two functions. PropertyDescriptors can only be created through the class methods [Accessor](#accessor), [Function](#function), or [Value](#value), each of which return a new static instance of a PropertyDescriptor. +A [`Napi::Object`](object.md) can be assigned properites via its [`DefineProperty`](object.md#defineproperty) and [`DefineProperties`](object.md#defineproperties) function, which take PropertyDescrptor(s) as their parameters. The `Napi::PropertyDescriptor` can contain either values or functions, which are then assigned to the `Napi::Object`. Note that a single instance of a `Napi::PropertyDescriptor` class can only contain either one value, or at most two functions. PropertyDescriptors can only be created through the class methods [`Accessor`](#accessor), [`Function`](#function), or [`Value`](#value), each of which return a new static instance of a `Napi::PropertyDescriptor`. ## Example @@ -52,7 +52,7 @@ Napi::PropertyDescriptor::PropertyDescriptor (napi_property_descriptor desc); ### Accessor ```cpp -static PropertyDescriptor Napi::PropertyDescriptor::Accessor (___ name, +static Napi::PropertyDescriptor Napi::PropertyDescriptor::Accessor (___ name, Getter getter, napi_property_attributes attributes = napi_default, void *data = nullptr); @@ -69,10 +69,10 @@ The name of the property can be any of the following types: - `const char*` - `const std::string &` - `napi_value value` -- `Name` +- `Napi::Name` ```cpp -static PropertyDescriptor Napi::PropertyDescriptor::Accessor (___ name, +static Napi::PropertyDescriptor Napi::PropertyDescriptor::Accessor (___ name, Getter getter, Setter setter, napi_property_attributes attributes = napi_default, @@ -85,18 +85,18 @@ static PropertyDescriptor Napi::PropertyDescriptor::Accessor (___ name, * `[in] attributes`: Potential attributes for the getter function. * `[in] data`: A pointer to data of any type, default is a null pointer. -Returns a PropertyDescriptor that contains a Getter and Setter function. +Returns a `Napi::PropertyDescriptor` that contains a `Getter` and `Setter` function. The name of the property can be any of the following types: - `const char*` - `const std::string &` - `napi_value value` -- `Name` +- `Napi::Name` ### Function ```cpp -static PropertyDescriptor Napi::PropertyDescriptor::Function (___ name, +static Napi::PropertyDescriptor Napi::PropertyDescriptor::Function (___ name, Callable cb, napi_property_attributes attributes = napi_default, void *data = nullptr); @@ -107,18 +107,18 @@ static PropertyDescriptor Napi::PropertyDescriptor::Function (___ name, * `[in] attributes`: Potential attributes for the getter function. * `[in] data`: A pointer to data of any type, default is a null pointer. -Returns a PropertyDescriptor that contains a callable Function. +Returns a `Napi::PropertyDescriptor` that contains a callable `Napi::Function`. The name of the property can be any of the following types: - `const char*` - `const std::string &` - `napi_value value` -- `Name` +- `Napi::Name` ### Value ```cpp -static PropertyDescriptor Napi::PropertyDescriptor::Value (___ name, +static Napi::PropertyDescriptor Napi::PropertyDescriptor::Value (___ name, napi_value value, napi_property_attributes attributes = napi_default); ``` @@ -127,7 +127,7 @@ The name of the property can be any of the following types: - `const char*` - `const std::string &` - `napi_value value` -- `Name` +- `Napi::Name` ## Related Information diff --git a/doc/range_error.md b/doc/range_error.md index e0bd14d30..c1c682367 100644 --- a/doc/range_error.md +++ b/doc/range_error.md @@ -1,11 +1,11 @@ # RangeError -The **RangeError** class is a representation of the JavaScript RangeError that is +The `Napi::RangeError` class is a representation of the JavaScript `RangeError` that is thrown when trying to pass a value as an argument to a function that does not allow a range that includes the value. -The **RangeError** class inherits its behaviors from the **Error** class (for -more info see: [Error](error.md)). +The `Napi::RangeError` class inherits its behaviors from the `Napi::Error` class (for +more info see: [`Napi::Error`](error.md)). For more details about error handling refer to the section titled [Error handling](error_handling.md). @@ -13,33 +13,33 @@ For more details about error handling refer to the section titled [Error handlin ### New -Creates a new instance of a `RangeError` object. +Creates a new instance of a `Napi::RangeError` object. ```cpp RangeError::New(Napi:Env env, const char* message); ``` -- `[in] Env`: The environment in which to construct the `RangeError` object. -- `[in] message`: Null-terminated string to be used as the message for the `RangeError`. +- `[in] Env`: The environment in which to construct the `Napi::RangeError` object. +- `[in] message`: Null-terminated string to be used as the message for the `Napi::RangeError`. -Returns an instance of a `RangeError` object. +Returns an instance of a `Napi::RangeError` object. ### New -Creates a new instance of a `RangeError` object. +Creates a new instance of a `Napi::RangeError` object. ```cpp RangeError::New(Napi:Env env, const std::string& message); ``` -- `[in] Env`: The environment in which to construct the `RangeError` object. -- `[in] message`: Reference string to be used as the message for the `RangeError`. +- `[in] Env`: The environment in which to construct the `Napi::RangeError` object. +- `[in] message`: Reference string to be used as the message for the `Napi::RangeError`. -Returns an instance of a `RangeError` object. +Returns an instance of a `Napi::RangeError` object. ### Constructor -Creates a new empty instance of a `RangeError`. +Creates a new empty instance of a `Napi::RangeError`. ```cpp RangeError(); @@ -47,13 +47,13 @@ RangeError(); ### Constructor -Initializes a `RangeError` instance from an existing Javascript error object. +Initializes a `Napi::RangeError` instance from an existing Javascript error object. ```cpp RangeError(napi_env env, napi_value value); ``` -- `[in] Env`: The environment in which to construct the `RangeError` object. -- `[in] value`: The `Error` reference to wrap. +- `[in] Env`: The environment in which to construct the `Napi::RangeError` object. +- `[in] value`: The `Napi::Error` reference to wrap. -Returns an instance of a `RangeError` object. \ No newline at end of file +Returns an instance of a `Napi::RangeError` object. diff --git a/doc/reference.md b/doc/reference.md index c25f98d8e..f5f1bd972 100644 --- a/doc/reference.md +++ b/doc/reference.md @@ -1,27 +1,23 @@ -You are reading a draft of the next documentation and it's in continuos update so -if you don't find what you need please refer to: -[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/) - # Reference (template) -Holds a counted reference to a [Value](value.md) object; initially a weak reference unless otherwise specified, may be changed to/from a strong reference by adjusting the refcount. +Holds a counted reference to a [`Napi::Value`](value.md) object; initially a weak reference unless otherwise specified, may be changed to/from a strong reference by adjusting the refcount. -The referenced Value is not immediately destroyed when the reference count is zero; it is merely then eligible for garbage-collection if there are no other references to the Value. +The referenced `Napi::Value` is not immediately destroyed when the reference count is zero; it is merely then eligible for garbage-collection if there are no other references to the `Napi::Value`. -Reference objects allocated in static space, such as a global static instance, must call the `SuppressDestruct` method to prevent its destructor, running at program shutdown time, from attempting to reset the reference when the environment is no longer valid. +`Napi::Reference` objects allocated in static space, such as a global static instance, must call the `SuppressDestruct` method to prevent its destructor, running at program shutdown time, from attempting to reset the reference when the environment is no longer valid. -The following classes inherit, either directly or indirectly, from Reference: +The following classes inherit, either directly or indirectly, from `Napi::Reference`: -* [ObjectWrap](object_wrap.md) -* [ObjectReference](object_reference.md) -* [FunctionReference](function_reference.md) +* [`Napi::ObjectWrap`](object_wrap.md) +* [`Napi::ObjectReference`](object_reference.md) +* [`Napi::FunctionReference`](function_reference.md) ## Methods ### Factory Method ```cpp -static Reference New(const T& value, uint32_t initialRefcount = 0); +static Napi::Reference New(const T& value, uint32_t initialRefcount = 0); ``` * `[in] value`: The value which is to be referenced. @@ -34,7 +30,7 @@ static Reference New(const T& value, uint32_t initialRefcount = 0); Reference(); ``` -Creates a new _empty_ Reference instance. +Creates a new _empty_ `Napi::Reference` instance. ### Constructor @@ -42,9 +38,9 @@ Creates a new _empty_ Reference instance. Reference(napi_env env, napi_value value); ``` -* `[in] env`: The `napi_env` environment in which to construct the Reference object. +* `[in] env`: The `napi_env` environment in which to construct the `Napi::Reference` object. -* `[in] value`: The N-API primitive value to be held by the Reference. +* `[in] value`: The N-API primitive value to be held by the `Napi::Reference`. ### Env @@ -52,7 +48,7 @@ Reference(napi_env env, napi_value value); Napi::Env Env() const; ``` -Returns the `Env` value in which the Reference was instantiated. +Returns the `Napi::Env` value in which the `Napi::Reference` was instantiated. ### IsEmpty @@ -60,7 +56,7 @@ Returns the `Env` value in which the Reference was instantiated. bool IsEmpty() const; ``` -Determines whether the value held by the Reference is empty. +Determines whether the value held by the `Napi::Reference` is empty. ### Value @@ -68,7 +64,7 @@ Determines whether the value held by the Reference is empty. T Value() const; ``` -Returns the value held by the Reference. +Returns the value held by the `Napi::Reference`. ### Ref @@ -76,7 +72,7 @@ Returns the value held by the Reference. uint32_t Ref(); ``` -Increments the reference count for the Reference and returns the resulting reference count. Throws an error if the increment fails. +Increments the reference count for the `Napi::Reference` and returns the resulting reference count. Throws an error if the increment fails. ### Unref @@ -84,7 +80,7 @@ Increments the reference count for the Reference and returns the resulting refer uint32_t Unref(); ``` -Decrements the reference count for the Reference and returns the resulting reference count. Throws an error if the decrement fails. +Decrements the reference count for the `Napi::Reference` and returns the resulting reference count. Throws an error if the decrement fails. ### Reset (Empty) @@ -92,7 +88,7 @@ Decrements the reference count for the Reference and returns the resulting refer void Reset(); ``` -Sets the value held by the Reference to be empty. +Sets the value held by the `Napi::Reference` to be empty. ### Reset @@ -104,7 +100,7 @@ void Reset(const T& value, uint32_t refcount = 0); * `[in] initialRefcount`: The initial reference count. -Sets the value held by the Reference. +Sets the value held by the `Napi::Reference`. ### SuppressDestruct @@ -112,4 +108,4 @@ Sets the value held by the Reference. void SuppressDestruct(); ``` -Call this method on a Reference that is declared as static data to prevent its destructor, running at program shutdown time, from attempting to reset the reference when the environment is no longer valid. +Call this method on a `Napi::Reference` that is declared as static data to prevent its destructor, running at program shutdown time, from attempting to reset the reference when the environment is no longer valid. diff --git a/doc/setup.md b/doc/setup.md index 176815a96..542729a69 100644 --- a/doc/setup.md +++ b/doc/setup.md @@ -19,7 +19,7 @@ To use **N-API** in a native module: ```json "dependencies": { - "node-addon-api": "1.2.0", + "node-addon-api": "*", } ``` diff --git a/doc/string.md b/doc/string.md index faa308a2d..14a33e4e9 100644 --- a/doc/string.md +++ b/doc/string.md @@ -6,7 +6,7 @@ String(); ``` -Returns a new **empty** String instance. +Returns a new **empty** `Napi::String` instance. If an error occurs, a `Napi::Error` will get thrown. If C++ exceptions are not being used, callers should check the result of `Env::IsExceptionPending` before @@ -48,7 +48,7 @@ Returns a UTF-16 encoded C++ string. String::New(); ``` -Returns a new empty String +Returns a new empty `Napi::String`. ### New ```cpp @@ -58,8 +58,8 @@ String::New(napi_env env, const char* value); String::New(napi_env env, const char16_t* value); ``` -- `[in] env`: The `napi_env` environment in which to construct the Value object. -- `[in] value`: The C++ primitive from which to instantiate the Value. `value` may be any of: +- `[in] env`: The `napi_env` environment in which to construct the `Napi::Value` object. +- `[in] value`: The C++ primitive from which to instantiate the `Napi::Value`. `value` may be any of: - `std::string&` - represents an ANSI string. - `std::u16string&` - represents a UTF16-LE string. - `const char*` - represents a UTF8 string. diff --git a/doc/symbol.md b/doc/symbol.md index fe7ee9c03..3330efd41 100644 --- a/doc/symbol.md +++ b/doc/symbol.md @@ -4,13 +4,13 @@ ### Constructor -Instantiates a new `Symbol` value +Instantiates a new `Napi::Symbol` value. ```cpp Symbol(); ``` -Returns a new empty Symbol. +Returns a new empty `Napi::Symbol`. ### New ```cpp @@ -20,8 +20,8 @@ Symbol::New(napi_env env, String description); Symbol::New(napi_env env, napi_value description); ``` -- `[in] env`: The `napi_env` environment in which to construct the Symbol object. -- `[in] value`: The C++ primitive which represents the description hint for the Symbol. +- `[in] env`: The `napi_env` environment in which to construct the `Napi::Symbol` object. +- `[in] value`: The C++ primitive which represents the description hint for the `Napi::Symbol`. `description` may be any of: - `std::string&` - ANSI string description. - `const char*` - represents a UTF8 string description. @@ -34,11 +34,11 @@ attempting to use the returned value. ### Utf8Value ```cpp -static Symbol WellKnown(napi_env env, const std::string& name); +static Napi::Symbol WellKnown(napi_env env, const std::string& name); ``` - `[in] env`: The `napi_env` environment in which to construct the Symbol object. -- `[in] name`: The C++ string representing the `Symbol` to retrieve. +- `[in] name`: The C++ string representing the `Napi::Symbol` to retrieve. -Returns a `Napi::Symbol` representing a well-known Symbol from the -Symbol registry. +Returns a `Napi::Symbol` representing a well-known `Symbol` from the +`Symbol` registry. diff --git a/doc/type_error.md b/doc/type_error.md index 7cfb9d1bf..28a2f7052 100644 --- a/doc/type_error.md +++ b/doc/type_error.md @@ -1,11 +1,11 @@ # TypeError -The **TypeError** class is a representation of the JavaScript `TypeError` that is +The `Napi::TypeError` class is a representation of the JavaScript `TypeError` that is thrown when an operand or argument passed to a function is incompatible with the type expected by the operator or function. -The **TypeError** class inherits its behaviors from the **Error** class (for more info -see: [Error](error.md)). +The `Napi::TypeError` class inherits its behaviors from the `Napi::Error` class (for more info +see: [`Napi::Error`](error.md)). For more details about error handling refer to the section titled [Error handling](error_handling.md). @@ -13,33 +13,33 @@ For more details about error handling refer to the section titled [Error handlin ### New -Creates a new instance of the `TypeError` object. +Creates a new instance of the `Napi::TypeError` object. ```cpp TypeError::New(Napi:Env env, const char* message); ``` -- `[in] Env`: The environment in which to construct the `TypeError` object. -- `[in] message`: Null-terminated string to be used as the message for the `TypeError`. +- `[in] Env`: The environment in which to construct the `Napi::TypeError` object. +- `[in] message`: Null-terminated string to be used as the message for the `Napi::TypeError`. -Returns an instance of a `TypeError` object. +Returns an instance of a `Napi::TypeError` object. ### New -Creates a new instance of a `TypeError` object. +Creates a new instance of a `Napi::TypeError` object. ```cpp TypeError::New(Napi:Env env, const std::string& message); ``` -- `[in] Env`: The environment in which to construct the `TypeError` object. -- `[in] message`: Reference string to be used as the message for the `TypeError`. +- `[in] Env`: The environment in which to construct the `Napi::TypeError` object. +- `[in] message`: Reference string to be used as the message for the `Napi::TypeError`. -Returns an instance of a `TypeError` object. +Returns an instance of a `Napi::TypeError` object. ### Constructor -Creates a new empty instance of a `TypeError`. +Creates a new empty instance of a `Napi::TypeError`. ```cpp TypeError(); @@ -47,13 +47,13 @@ TypeError(); ### Constructor -Initializes a ```TypeError``` instance from an existing JavaScript error object. +Initializes a `Napi::TypeError` instance from an existing JavaScript error object. ```cpp TypeError(napi_env env, napi_value value); ``` -- `[in] Env`: The environment in which to construct the `TypeError` object. -- `[in] value`: The `Error` reference to wrap. +- `[in] Env`: The environment in which to construct the `Napi::TypeError` object. +- `[in] value`: The `Napi::Error` reference to wrap. -Returns an instance of a `TypeError` object. \ No newline at end of file +Returns an instance of a `Napi::TypeError` object. diff --git a/doc/typed_array.md b/doc/typed_array.md index f96d36499..63063aef6 100644 --- a/doc/typed_array.md +++ b/doc/typed_array.md @@ -1,6 +1,6 @@ # TypedArray -The `TypedArray` class corresponds to the +The `Napi::TypedArray` class corresponds to the [JavaScript `TypedArray`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray) class. @@ -8,7 +8,7 @@ class. ### Constructor -Initializes an empty instance of the `TypedArray` class. +Initializes an empty instance of the `Napi::TypedArray` class. ```cpp TypedArray(); @@ -16,14 +16,14 @@ TypedArray(); ### Constructor -Initializes a wrapper instance of an existing `TypedArray` instance. +Initializes a wrapper instance of an existing `Napi::TypedArray` instance. ```cpp TypedArray(napi_env env, napi_value value); ``` -- `[in] env`: The environment in which to create the `TypedArray` instance. -- `[in] value`: The `TypedArray` reference to wrap. +- `[in] env`: The environment in which to create the `Napi::TypedArray` instance. +- `[in] value`: The `Napi::TypedArray` reference to wrap. ### TypedArrayType @@ -63,7 +63,7 @@ Returns the number of elements. size_t ByteOffset() const; ``` -Returns the offset into the `ArrayBuffer` where the array starts, in bytes. +Returns the offset into the `Napi::ArrayBuffer` where the array starts, in bytes. ### ByteLength diff --git a/doc/typed_array_of.md b/doc/typed_array_of.md index 868e5ec44..f11c47bf8 100644 --- a/doc/typed_array_of.md +++ b/doc/typed_array_of.md @@ -1,6 +1,6 @@ # TypedArrayOf -The `TypedArrayOf` class corresponds to the various +The `Napi::TypedArrayOf` class corresponds to the various [JavaScript `TypedArray`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray) classes. @@ -9,14 +9,14 @@ classes. The common JavaScript `TypedArray` types are pre-defined for each of use: ```cpp -typedef TypedArrayOf Int8Array; -typedef TypedArrayOf Uint8Array; -typedef TypedArrayOf Int16Array; -typedef TypedArrayOf Uint16Array; -typedef TypedArrayOf Int32Array; -typedef TypedArrayOf Uint32Array; -typedef TypedArrayOf Float32Array; -typedef TypedArrayOf Float64Array; +typedef Napi::TypedArrayOf Int8Array; +typedef Napi::TypedArrayOf Uint8Array; +typedef Napi::TypedArrayOf Int16Array; +typedef Napi::TypedArrayOf Uint16Array; +typedef Napi::TypedArrayOf Int32Array; +typedef Napi::TypedArrayOf Uint32Array; +typedef Napi::TypedArrayOf Float32Array; +typedef Napi::TypedArrayOf Float64Array; ``` The one exception is the `Uint8ClampedArray` which requires explicit @@ -33,51 +33,51 @@ behavior is only applied in JavaScript. ### New -Allocates a new `TypedArray` instance with a given length. The underlying -`ArrayBuffer` is allocated automatically to the desired number of elements. +Allocates a new `Napi::TypedArray` instance with a given length. The underlying +`Napi::ArrayBuffer` is allocated automatically to the desired number of elements. The array type parameter can normally be omitted (because it is inferred from the template parameter T), except when creating a "clamped" array. ```cpp -static TypedArrayOf New(napi_env env, +static Napi::TypedArrayOf New(napi_env env, size_t elementLength, napi_typedarray_type type); ``` -- `[in] env`: The environment in which to create the `TypedArrayOf` instance. +- `[in] env`: The environment in which to create the `Napi::TypedArrayOf` instance. - `[in] elementLength`: The length to be allocated, in elements. - `[in] type`: The type of array to allocate (optional). -Returns a new `TypedArrayOf` instance. +Returns a new `Napi::TypedArrayOf` instance. ### New -Wraps the provided `ArrayBuffer` into a new `TypedArray` instance. +Wraps the provided `Napi::ArrayBuffer` into a new `Napi::TypedArray` instance. The array `type` parameter can normally be omitted (because it is inferred from the template parameter `T`), except when creating a "clamped" array. ```cpp -static TypedArrayOf New(napi_env env, +static Napi::TypedArrayOf New(napi_env env, size_t elementLength, Napi::ArrayBuffer arrayBuffer, size_t bufferOffset, napi_typedarray_type type); ``` -- `[in] env`: The environment in which to create the `TypedArrayOf` instance. +- `[in] env`: The environment in which to create the `Napi::TypedArrayOf` instance. - `[in] elementLength`: The length to array, in elements. -- `[in] arrayBuffer`: The backing `ArrayBuffer` instance. -- `[in] bufferOffset`: The offset into the `ArrayBuffer` where the array starts, +- `[in] arrayBuffer`: The backing `Napi::ArrayBuffer` instance. +- `[in] bufferOffset`: The offset into the `Napi::ArrayBuffer` where the array starts, in bytes. - `[in] type`: The type of array to allocate (optional). -Returns a new `TypedArrayOf` instance. +Returns a new `Napi::TypedArrayOf` instance. ### Constructor -Initializes an empty instance of the `TypedArrayOf` class. +Initializes an empty instance of the `Napi::TypedArrayOf` class. ```cpp TypedArrayOf(); @@ -85,14 +85,14 @@ TypedArrayOf(); ### Constructor -Initializes a wrapper instance of an existing `TypedArrayOf` object. +Initializes a wrapper instance of an existing `Napi::TypedArrayOf` object. ```cpp TypedArrayOf(napi_env env, napi_value value); ``` -- `[in] env`: The environment in which to create the `TypedArrayOf` object. -- `[in] value`: The `TypedArrayOf` reference to wrap. +- `[in] env`: The environment in which to create the `Napi::TypedArrayOf` object. +- `[in] value`: The `Napi::TypedArrayOf` reference to wrap. ### operator [] @@ -120,7 +120,7 @@ Returns the element found at the given index. T* Data() const; ``` -Returns a pointer into the backing `ArrayBuffer` which is offset to point to the +Returns a pointer into the backing `Napi::ArrayBuffer` which is offset to point to the start of the array. ### Data @@ -129,5 +129,5 @@ start of the array. const T* Data() const ``` -Returns a pointer into the backing `ArrayBuffer` which is offset to point to the +Returns a pointer into the backing `Napi::ArrayBuffer` which is offset to point to the start of the array. diff --git a/doc/value.md b/doc/value.md index 5e79d352e..b7e3b766a 100644 --- a/doc/value.md +++ b/doc/value.md @@ -6,21 +6,21 @@ Value is the C++ manifestation of a JavaScript value. Value is a the base class upon which other JavaScript values such as Number, Boolean, String, and Object are based. -The following classes inherit, either directly or indirectly, from Value: - -- [Array](array.md) -- [ArrayBuffer](array_buffer.md) -- [Boolean](boolean.md) -- [Buffer](buffer.md) -- [External](external.md) -- [Function](function.md) -- [Name](name.md) -- [Number](number.md) -- [Object](object.md) -- [String](string.md) -- [Symbol](symbol.md) -- [TypedArray](typed_array.md) -- [TypedArrayOf](typed_array_of.md) +The following classes inherit, either directly or indirectly, from `Napi::Value`: + +- [`Napi::Array`](array.md) +- [`Napi::ArrayBuffer`](array_buffer.md) +- [`Napi::Boolean`](boolean.md) +- [`Napi::Buffer`](buffer.md) +- [`Napi::External`](external.md) +- [`Napi::Function`](function.md) +- [`Napi::Name`](name.md) +- [`Napi::Number`](number.md) +- [`Napi::Object`](object.md) +- [`Napi::String`](string.md) +- [`Napi::Symbol`](symbol.md) +- [`Napi::TypedArray`](typed_array.md) +- [`Napi::TypedArrayOf`](typed_array_of.md) ## Methods @@ -30,7 +30,7 @@ The following classes inherit, either directly or indirectly, from Value: Value(); ``` -Creates a new *empty* Value instance. +Creates a new *empty* `Napi::Value` instance. ### Constructor @@ -38,9 +38,9 @@ Creates a new *empty* Value instance. Value(napi_env env, napi_value value); ``` -- `[in] env`: The `napi_env` environment in which to construct the Value object. +- `[in] env`: The `napi_env` environment in which to construct the `Napi::Value` object. -- `[in] value`: The C++ primitive from which to instantiate the Value. `value` may be any of: +- `[in] value`: The C++ primitive from which to instantiate the `Napi::Value`. `value` may be any of: - bool - Any integer type - Any floating point type @@ -48,18 +48,18 @@ Value(napi_env env, napi_value value); - const char16_t* (encoded using UTF-16-LE, null-terminated) - std::string (encoded using UTF-8) - std::u16string - - napi::Value + - Napi::Value - napi_value ### From ```cpp -template static Value From(napi_env env, const T& value); +template static Napi::Value From(napi_env env, const T& value); ``` -- `[in] env`: The `napi_env` environment in which to create the Value object. +- `[in] env`: The `napi_env` environment in which to create the `Napi::Value` object. -- `[in] value`: The N-API primitive value from which to create the Value object. +- `[in] value`: The N-API primitive value from which to create the `Napi::Value` object. Returns a Value object from an N-API primitive value. @@ -71,7 +71,7 @@ operator napi_value() const; Returns this Value's N-API value primitive. -Returns `nullptr` if this Value is *empty*. +Returns `nullptr` if this `Napi::Value` is *empty*. ### operator == @@ -79,9 +79,9 @@ Returns `nullptr` if this Value is *empty*. bool operator ==(const Value& other) const; ``` -- `[in] other`: The Value object to be compared. +- `[in] other`: The `Napi::Value` object to be compared. -Returns a `bool` indicating if this Value strictly equals another Value. +Returns a `bool` indicating if this `Napi::Value` strictly equals another `Napi::Value`. ### operator != @@ -91,16 +91,16 @@ bool operator !=(const Value& other) const; - `[in] other`: The Value object to be compared. -Returns a `bool` indicating if this Value does not strictly equal another Value. +Returns a `bool` indicating if this `Napi::Value` does not strictly equal another `Napi::Value`. ### StrictEquals ```cpp bool StrictEquals(const Value& other) const; ``` -- `[in] other`: The Value object to be compared. +- `[in] other`: The `Napi::Value` object to be compared. -Returns a `bool` indicating if this Value strictly equals another Value. +Returns a `bool` indicating if this `Napi::Value` strictly equals another `Napi::Value`. ### Env @@ -108,7 +108,7 @@ Returns a `bool` indicating if this Value strictly equals another Value. Napi::Env Env() const; ``` -Returns the `Env` environment this value is associated with. +Returns the `Napi::Env` environment this value is associated with. ### IsEmpty @@ -116,11 +116,12 @@ Returns the `Env` environment this value is associated with. bool IsEmpty() const; ``` -Returns a `bool` indicating if this Value is *empty* (uninitialized). +Returns a `bool` indicating if this `Napi::Value` is *empty* (uninitialized). -An empty Value is invalid, and most attempts to perform an operation on an empty Value will result in an exception. Note an empty Value is distinct from JavaScript `null` or `undefined`, which are valid values. +An empty `Napi::Value` is invalid, and most attempts to perform an operation on an empty Value will result in an exception. +Note an empty `Napi::Value` is distinct from JavaScript `null` or `undefined`, which are valid values. -When C++ exceptions are disabled at compile time, a method with a `Value` return type may return an empty Value to indicate a pending exception. So when not using C++ exceptions, callers should check whether this Value is empty before attempting to use it. +When C++ exceptions are disabled at compile time, a method with a `Napi::Value` return type may return an empty Value to indicate a pending exception. So when not using C++ exceptions, callers should check whether this `Napi::Value` is empty before attempting to use it. ### Type @@ -128,7 +129,7 @@ When C++ exceptions are disabled at compile time, a method with a `Value` return napi_valuetype Type() const; ``` -Returns the `napi_valuetype` type of the Value. +Returns the `napi_valuetype` type of the `Napi::Value`. ### IsUndefined @@ -136,7 +137,7 @@ Returns the `napi_valuetype` type of the Value. bool IsUndefined() const; ``` -Returns a `bool` indicating if this Value is an undefined JavaScript value. +Returns a `bool` indicating if this `Napi::Value` is an undefined JavaScript value. ### IsNull @@ -144,7 +145,7 @@ Returns a `bool` indicating if this Value is an undefined JavaScript value. bool IsNull() const; ``` -Returns a `bool` indicating if this Value is a null JavaScript value. +Returns a `bool` indicating if this `Napi::Value` is a null JavaScript value. ### IsBoolean @@ -152,7 +153,7 @@ Returns a `bool` indicating if this Value is a null JavaScript value. bool IsBoolean() const; ``` -Returns a `bool` indicating if this Value is a JavaScript boolean. +Returns a `bool` indicating if this `Napi::Value` is a JavaScript boolean. ### IsNumber @@ -160,7 +161,7 @@ Returns a `bool` indicating if this Value is a JavaScript boolean. bool IsNumber() const; ``` -Returns a `bool` indicating if this Value is a JavaScript number. +Returns a `bool` indicating if this `Napi::Value` is a JavaScript number. ### IsString @@ -168,7 +169,7 @@ Returns a `bool` indicating if this Value is a JavaScript number. bool IsString() const; ``` -Returns a `bool` indicating if this Value is a JavaScript string. +Returns a `bool` indicating if this `Napi::Value` is a JavaScript string. ### IsSymbol @@ -176,7 +177,7 @@ Returns a `bool` indicating if this Value is a JavaScript string. bool IsSymbol() const; ``` -Returns a `bool` indicating if this Value is a JavaScript symbol. +Returns a `bool` indicating if this `Napi::Value` is a JavaScript symbol. ### IsArray @@ -184,7 +185,7 @@ Returns a `bool` indicating if this Value is a JavaScript symbol. bool IsArray() const; ``` -Returns a `bool` indicating if this Value is a JavaScript array. +Returns a `bool` indicating if this `Napi::Value` is a JavaScript array. ### IsArrayBuffer @@ -192,7 +193,7 @@ Returns a `bool` indicating if this Value is a JavaScript array. bool IsArrayBuffer() const; ``` -Returns a `bool` indicating if this Value is a JavaScript array buffer. +Returns a `bool` indicating if this `Napi::Value` is a JavaScript array buffer. ### IsTypedArray @@ -200,7 +201,7 @@ Returns a `bool` indicating if this Value is a JavaScript array buffer. bool IsTypedArray() const; ``` -Returns a `bool` indicating if this Value is a JavaScript typed array. +Returns a `bool` indicating if this `Napi::Value` is a JavaScript typed array. ### IsObject @@ -208,7 +209,7 @@ Returns a `bool` indicating if this Value is a JavaScript typed array. bool IsObject() const; ``` -Returns a `bool` indicating if this Value is JavaScript object. +Returns a `bool` indicating if this `Napi::Value` is JavaScript object. ### IsFunction @@ -216,7 +217,7 @@ Returns a `bool` indicating if this Value is JavaScript object. bool IsFunction() const; ``` -Returns a `bool` indicating if this Value is a JavaScript function. +Returns a `bool` indicating if this `Napi::Value` is a JavaScript function. ### IsBuffer @@ -224,7 +225,7 @@ Returns a `bool` indicating if this Value is a JavaScript function. bool IsBuffer() const; ``` -Returns a `bool` indicating if this Value is a Node buffer. +Returns a `bool` indicating if this `Napi::Value` is a Node buffer. ### As @@ -242,7 +243,7 @@ This conversion does not coerce the type. Calling any methods inappropriate for Boolean ToBoolean() const; ``` -Returns the Value coerced to a JavaScript boolean. +Returns the `Napi::Value` coerced to a JavaScript boolean. ### ToNumber @@ -250,7 +251,7 @@ Returns the Value coerced to a JavaScript boolean. Number ToNumber() const; ``` -Returns the Value coerced to a JavaScript number. +Returns the `Napi::Value` coerced to a JavaScript number. ### ToString @@ -258,7 +259,7 @@ Returns the Value coerced to a JavaScript number. String ToString() const; ``` -Returns the Value coerced to a JavaScript string. +Returns the `Napi::Value` coerced to a JavaScript string. ### ToObject @@ -266,4 +267,4 @@ Returns the Value coerced to a JavaScript string. Object ToObject() const; ``` -Returns the Value coerced to a JavaScript object. +Returns the `Napi::Value` coerced to a JavaScript object. From b9955e3ae5bbc653fdb02d3f924c5ae5699957ed Mon Sep 17 00:00:00 2001 From: NickNaso Date: Tue, 11 Sep 2018 11:12:35 +0200 Subject: [PATCH 2/9] Removed work in progress comment --- doc/value.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/doc/value.md b/doc/value.md index b7e3b766a..716446edf 100644 --- a/doc/value.md +++ b/doc/value.md @@ -1,8 +1,6 @@ -**WORK IN PROGRESS, NOT YET COMPLETE** - # Value -Value is the C++ manifestation of a JavaScript value. +`Napi::Value` is the C++ manifestation of a JavaScript value. Value is a the base class upon which other JavaScript values such as Number, Boolean, String, and Object are based. From c5c8d5a0dfa6e5a17ceebf703e354d6d65ac483c Mon Sep 17 00:00:00 2001 From: NickNaso Date: Mon, 17 Sep 2018 23:44:43 +0200 Subject: [PATCH 3/9] Added some changes to clean documentation --- doc/array_buffer.md | 16 ++++---- doc/async_worker.md | 32 ++++++++-------- doc/basic_types.md | 70 +++++++++++++++++------------------ doc/boolean.md | 4 +- doc/buffer.md | 18 ++++----- doc/callbackinfo.md | 18 ++++----- doc/env.md | 12 +++--- doc/error.md | 18 ++++----- doc/escapable_handle_scope.md | 12 +++--- doc/external.md | 8 ++-- doc/function.md | 32 ++++++++-------- doc/function_reference.md | 24 ++++++------ doc/handle_scope.md | 10 ++--- doc/number.md | 12 +++--- doc/object_reference.md | 14 +++---- doc/promises.md | 12 +++--- doc/range_error.md | 8 ++-- doc/reference.md | 22 +++++------ doc/string.md | 18 ++++----- doc/symbol.md | 14 +++---- doc/type_error.md | 8 ++-- doc/typed_array.md | 16 ++++---- doc/typed_array_of.md | 12 +++--- doc/value.md | 62 +++++++++++++++---------------- 24 files changed, 236 insertions(+), 236 deletions(-) diff --git a/doc/array_buffer.md b/doc/array_buffer.md index 8f76b992f..e7217d73a 100644 --- a/doc/array_buffer.md +++ b/doc/array_buffer.md @@ -11,7 +11,7 @@ class. Allocates a new `Napi::ArrayBuffer` instance with a given length. ```cpp -static Napi::ArrayBuffer New(napi_env env, size_t byteLength); +static Napi::ArrayBuffer Napi::ArrayBuffer::New(napi_env env, size_t byteLength); ``` - `[in] env`: The environment in which to create the `Napi::ArrayBuffer` instance. @@ -29,7 +29,7 @@ expects it to be valid for the lifetime of the instance. Since the suitable for data which is static and never needs to be freed. ```cpp -static Napi::ArrayBuffer New(napi_env env, void* externalData, size_t byteLength); +static Napi::ArrayBuffer Napi::ArrayBuffer::New(napi_env env, void* externalData, size_t byteLength); ``` - `[in] env`: The environment in which to create the `Napi::ArrayBuffer` instance. @@ -49,7 +49,7 @@ freed once the `finalizeCallback` is invoked to indicate that the ```cpp template -static Napi::ArrayBuffer New(napi_env env, +static Napi::ArrayBuffer Napi::ArrayBuffer::New(napi_env env, void* externalData, size_t byteLength, Finalizer finalizeCallback); @@ -75,7 +75,7 @@ released. ```cpp template -static Napi::ArrayBuffer New(napi_env env, +static Napi::ArrayBuffer Napi::ArrayBuffer::New(napi_env env, void* externalData, size_t byteLength, Finalizer finalizeCallback, @@ -98,7 +98,7 @@ Returns a new `Napi::ArrayBuffer` instance. Initializes an empty instance of the `Napi::ArrayBuffer` class. ```cpp -ArrayBuffer(); +Napi::ArrayBuffer::ArrayBuffer(); ``` ### Constructor @@ -106,7 +106,7 @@ ArrayBuffer(); Initializes a wrapper instance of an existing `Napi::ArrayBuffer` object. ```cpp -ArrayBuffer(napi_env env, napi_value value); +Napi::ArrayBuffer::ArrayBuffer(napi_env env, napi_value value); ``` - `[in] env`: The environment in which to create the `Napi::ArrayBuffer` instance. @@ -115,7 +115,7 @@ ArrayBuffer(napi_env env, napi_value value); ### ByteLength ```cpp -size_t ByteLength() const; +size_t Napi::ArrayBuffer::ByteLength() const; ``` Returns the length of the wrapped data, in bytes. @@ -123,7 +123,7 @@ Returns the length of the wrapped data, in bytes. ### Data ```cpp -T* Data() const; +T* Napi::ArrayBuffer::Data() const; ``` Returns a pointer the wrapped data. diff --git a/doc/async_worker.md b/doc/async_worker.md index fa9d7c34e..ad04eb04e 100644 --- a/doc/async_worker.md +++ b/doc/async_worker.md @@ -20,7 +20,7 @@ subclass. Requests the environment in which the async worker has been initially created. ```cpp -Napi::Env Env() const; +Napi::Env Napi::AsyncWorker::Env() const; ``` Returns the environment in which the async worker has been created. @@ -30,7 +30,7 @@ Returns the environment in which the async worker has been created. Requests that the work be queued for execution. ```cpp -void Queue(); +void Napi::AsyncWorker::Queue(); ``` ### Cancel @@ -40,13 +40,13 @@ executing, it cannot be cancelled. If cancelled successfully neither `OnOK` nor `OnError` will be called. ```cpp -void Cancel(); +void Napi::AsyncWorker::Cancel(); ``` ### Receiver ```cpp -Napi::ObjectReference& Receiver(); +Napi::ObjectReference& Napi::AsyncWorker::Receiver(); ``` Returns the persistent object reference of the receiver object set when the async @@ -55,7 +55,7 @@ worker was created. ### Callback ```cpp -Napi::FunctionReference& Callback(); +Napi::FunctionReference& Napi::AsyncWorker::Callback(); ``` Returns the persistent function reference of the callback set when the async @@ -70,7 +70,7 @@ an error message will cause the `OnError` method to be invoked instead of `OnOK` once the `Execute` method completes. ```cpp -void SetError(const std::string& error); +void Napi::AsyncWorker::SetError(const std::string& error); ``` - `[in] error`: The reference to the string that represent the message of the error. @@ -87,7 +87,7 @@ in the `OnOK` method which runs on the main thread and is invoked when the `Exec method completes. ```cpp -virtual void Execute() = 0; +virtual void Napi::AsyncWorker::Execute() = 0; ``` ### OnOK @@ -97,7 +97,7 @@ The default implementation runs the Callback provided when the AsyncWorker class was created. ```cpp -virtual void OnOK(); +virtual void Napi::AsyncWorker::OnOK(); ``` ### OnError @@ -109,7 +109,7 @@ calls the callback provided when the AsyncWorker class was created, passing in the error as the first parameter. ```cpp -virtual void OnError(const Error& e); +virtual void Napi::AsyncWorker::OnError(const Error& e); ``` ### Constructor @@ -117,7 +117,7 @@ virtual void OnError(const Error& e); Creates a new `Napi::AsyncWorker`. ```cpp -explicit AsyncWorker(const Function& callback); +explicit Napi::AsyncWorker(const Function& callback); ``` - `[in] callback`: The function which will be called when an asynchronous @@ -131,7 +131,7 @@ Returns a`Napi::AsyncWork` instance which can later be queued for execution by c Creates a new `Napi::AsyncWorker`. ```cpp -explicit AsyncWorker(const Function& callback, const char* resource_name); +explicit Napi::AsyncWorker(const Function& callback, const char* resource_name); ``` - `[in] callback`: The function which will be called when an asynchronous @@ -148,7 +148,7 @@ Returns a `Napi::AsyncWork` instance which can later be queued for execution by Creates a new `Napi::AsyncWorker`. ```cpp -explicit AsyncWorker(const Function& callback, const char* resource_name, const Object& resource); +explicit Napi::AsyncWorker(const Function& callback, const char* resource_name, const Object& resource); ``` - `[in] callback`: The function which will be called when an asynchronous @@ -167,7 +167,7 @@ Returns a `Napi::AsyncWork` instance which can later be queued for execution by Creates a new `Napi::AsyncWorker`. ```cpp -explicit AsyncWorker(const Object& receiver, const Function& callback); +explicit Napi::AsyncWorker(const Object& receiver, const Function& callback); ``` - `[in] receiver`: The `this` object passed to the called function. @@ -182,7 +182,7 @@ Returns a `Napi::AsyncWork` instance which can later be queued for execution by Creates a new `Napi::AsyncWorker`. ```cpp -explicit AsyncWorker(const Object& receiver, const Function& callback,const char* resource_name); +explicit Napi::AsyncWorker(const Object& receiver, const Function& callback,const char* resource_name); ``` - `[in] receiver`: The `this` object passed to the called function. @@ -200,7 +200,7 @@ Returns a `Napi::AsyncWork` instance which can later be queued for execution by Creates a new `Napi::AsyncWorker`. ```cpp -explicit AsyncWorker(const Object& receiver, const Function& callback, const char* resource_name, const Object& resource); +explicit Napi::AsyncWorker(const Object& receiver, const Function& callback, const char* resource_name, const Object& resource); ``` - `[in] receiver`: The `this` object passed to the called function. @@ -220,7 +220,7 @@ Returns a `Napi::AsyncWork` instance which can later be queued for execution by Deletes the created work object that is used to execute logic asynchronously. ```cpp -virtual ~AsyncWorker(); +virtual Napi::~AsyncWorker(); ``` ## Operator diff --git a/doc/basic_types.md b/doc/basic_types.md index 893cb30ac..72033f1bb 100644 --- a/doc/basic_types.md +++ b/doc/basic_types.md @@ -15,13 +15,13 @@ C++ types. ### Constructor ```cpp -Value(); +Napi::Value::Value(); ``` Used to create a Node Addon API `Napi::Value` that represents an **empty** value. ```cpp -Value(napi_env env, napi_value value); +Napi::Value::Value(napi_env env, napi_value value); ``` - `[in] env` - The `napi_env` environment in which to construct the `Napi::Value` @@ -64,7 +64,7 @@ Returns `false` if this value strictly equals another value, or `true` otherwise #### From ```cpp template -static Napi::Value From(napi_env env, const T& value); +static Napi::Value Napi::Value::From(napi_env env, const T& value); ``` - `[in] env` - The `napi_env` environment in which to construct the `Napi::Value` object. @@ -86,7 +86,7 @@ Here, `value` may be any of: #### As ```cpp -template T As() const; +template T Napi::Value::As() const; ``` Returns the `Napi::Value` cast to a desired C++ type. @@ -99,7 +99,7 @@ the actual value type will throw `Napi::Error`. #### StrictEquals ```cpp -bool StrictEquals(const Value& other) const; +bool Napi::Value::StrictEquals(const Value& other) const; ``` - `[in] other` - The value to compare against. @@ -108,7 +108,7 @@ Returns true if the other `Napi::Value` is strictly equal to this one. #### Env ```cpp -Napi::Env Env() const; +Napi::Env Napi::Value::Env() const; ``` Returns the environment that the value is associated with. See @@ -116,7 +116,7 @@ Returns the environment that the value is associated with. See #### IsEmpty ```cpp -bool IsEmpty() const; +bool Napi::Value::IsEmpty() const; ``` Returns `true` if the value is uninitialized. @@ -132,14 +132,14 @@ exceptions are not being used, callers should check the result of #### Type ```cpp -napi_valuetype Type() const; +napi_valuetype Napi::Value::Type() const; ``` Returns the underlying N-API `napi_valuetype` of the value. #### IsUndefined ```cpp -bool IsUndefined() const; +bool Napi::Value::IsUndefined() const; ``` Returns `true` if the underlying value is a JavaScript `undefined` or `false` @@ -147,7 +147,7 @@ otherwise. #### IsNull ```cpp -bool IsNull() const; +bool Napi::Value::IsNull() const; ``` Returns `true` if the underlying value is a JavaScript `null` or `false` @@ -155,7 +155,7 @@ otherwise. #### IsBoolean ```cpp -bool IsBoolean() const; +bool Napi::Value::IsBoolean() const; ``` Returns `true` if the underlying value is a JavaScript `true` or JavaScript @@ -163,7 +163,7 @@ Returns `true` if the underlying value is a JavaScript `true` or JavaScript #### IsNumber ```cpp -bool IsNumber() const; +bool Napi::Value::IsNumber() const; ``` Returns `true` if the underlying value is a JavaScript `Napi::Number` or `false` @@ -171,7 +171,7 @@ otherwise. #### IsString ```cpp -bool IsString() const; +bool Napi::Value::IsString() const; ``` Returns `true` if the underlying value is a JavaScript `Napi::String` or `false` @@ -179,7 +179,7 @@ otherwise. #### IsSymbol ```cpp -bool IsSymbol() const; +bool Napi::Value::IsSymbol() const; ``` Returns `true` if the underlying value is a JavaScript `Napi::Symbol` or `false` @@ -187,7 +187,7 @@ otherwise. #### IsArray ```cpp -bool IsArray() const; +bool Napi::Value::IsArray() const; ``` Returns `true` if the underlying value is a JavaScript `Napi::Array` or `false` @@ -195,7 +195,7 @@ otherwise. #### IsArrayBuffer ```cpp -bool IsArrayBuffer() const; +bool Napi::Value::IsArrayBuffer() const; ``` Returns `true` if the underlying value is a JavaScript `Napi::ArrayBuffer` or `false` @@ -203,7 +203,7 @@ otherwise. #### IsTypedArray ```cpp -bool IsTypedArray() const; +bool Napi::Value::IsTypedArray() const; ``` Returns `true` if the underlying value is a JavaScript `Napi::TypedArray` or `false` @@ -211,7 +211,7 @@ otherwise. #### IsObject ```cpp -bool IsObject() const; +bool Napi::Value::IsObject() const; ``` Returns `true` if the underlying value is a JavaScript `Napi::Object` or `false` @@ -219,7 +219,7 @@ otherwise. #### IsFunction ```cpp -bool IsFunction() const; +bool Napi::Value::IsFunction() const; ``` Returns `true` if the underlying value is a JavaScript `Napi::Function` or `false` @@ -227,7 +227,7 @@ otherwise. #### IsPromise ```cpp -bool IsPromise() const; +bool Napi::Value::IsPromise() const; ``` Returns `true` if the underlying value is a JavaScript `Napi::Promise` or `false` @@ -235,7 +235,7 @@ otherwise. #### IsDataView ```cpp -bool IsDataView() const; +bool Napi::Value::IsDataView() const; ``` Returns `true` if the underlying value is a JavaScript `Napi::DataView` or `false` @@ -243,7 +243,7 @@ otherwise. #### IsBuffer ```cpp -bool IsBuffer() const; +bool Napi::Value::IsBuffer() const; ``` Returns `true` if the underlying value is a Node.js `Napi::Buffer` or `false` @@ -251,7 +251,7 @@ otherwise. #### IsExternal ```cpp -bool IsExternal() const; +bool Napi::Value::IsExternal() const; ``` Returns `true` if the underlying value is a N-API external object or `false` @@ -259,7 +259,7 @@ otherwise. #### ToBoolean ```cpp -Boolean ToBoolean() const; +Boolean Napi::Value::ToBoolean() const; ``` Returns a `Napi::Boolean` representing the `Napi::Value`. @@ -271,7 +271,7 @@ the returned value. #### ToNumber ```cpp -Napi::Number ToNumber() const; +Napi::Number Napi::Value::ToNumber() const; ``` Returns a `Napi::Number` representing the `Napi::Value`. @@ -285,7 +285,7 @@ the returned value. #### ToString ```cpp -Napi::String ToString() const; +Napi::String Napi::Value::ToString() const; ``` Returns a `Napi::String` representing the `Napi::Value`. @@ -298,7 +298,7 @@ attempting to use the returned value. #### ToObject ```cpp -Napi::Object ToObject() const; +Napi::Object Napi::Value::ToObject() const; ``` Returns a `Napi::Object` representing the `Napi::Value`. @@ -318,13 +318,13 @@ and [`Napi::Symbol`](symbol.md). #### Constructor ```cpp -Name(); +Napi::Name::Name(); ``` Returns an empty `Napi::Name`. ```cpp -Name(napi_env env, napi_value value); +Napi::Name::Name(napi_env env, napi_value value); ``` - `[in] env` - The environment in which to create the array. - `[in] value` - The primitive to wrap. @@ -341,7 +341,7 @@ around `napi_value` representing a JavaScript Array. ### Constructor ```cpp -Array(); +Napi::Array::Array(); ``` Returns an empty array. @@ -351,7 +351,7 @@ being used, callers should check the result of `Env::IsExceptionPending` before attempting to use the returned value. ```cpp -Array(napi_env env, napi_value value); +Napi::Array::Array(napi_env env, napi_value value); ``` - `[in] env` - The environment in which to create the array. - `[in] value` - The primitive to wrap. @@ -366,7 +366,7 @@ attempting to use the returned value. #### New ```cpp -static Napi::Array New(napi_env env); +static Napi::Array Napi::Array::New(napi_env env); ``` - `[in] env` - The environment in which to create the array. @@ -379,7 +379,7 @@ attempting to use the returned value. #### New ```cpp -static Napi::Array New(napi_env env, size_t length); +static Napi::Array Napi::Array::New(napi_env env, size_t length); ``` - `[in] env` - The environment in which to create the array. - `[in] length` - The length of the array. @@ -390,9 +390,9 @@ If an error occurs, a `Napi::Error` will get thrown. If C++ exceptions are not being used, callers should check the result of `Env::IsExceptionPending` before attempting to use the returned value. -#### New +#### Length ```cpp -uint32_t Length() const; +uint32_t Napi::Array::Length() const; ``` Returns the length of the array. diff --git a/doc/boolean.md b/doc/boolean.md index 80b420ba5..a6d234dbe 100644 --- a/doc/boolean.md +++ b/doc/boolean.md @@ -11,7 +11,7 @@ Napi::Boolean::New(Napi::Env env, bool value); - `[in] value`: The Javascript boolean value ```cpp -Napi::Boolean(); +Napi::Boolean::Boolean(); ``` returns a new empty Javascript Boolean value type. @@ -25,5 +25,5 @@ operator bool() const; Converts a `Napi::Boolean` value to a boolean primitive. ```cpp -bool Value() const; +bool Napi::Boolean::Value() const; ``` diff --git a/doc/buffer.md b/doc/buffer.md index d699c1f6d..8f76b200d 100644 --- a/doc/buffer.md +++ b/doc/buffer.md @@ -10,7 +10,7 @@ script. Allocates a new `Napi::Buffer` object with a given length. ```cpp -static Napi::Buffer New(napi_env env, size_t length); +static Napi::Buffer Napi::Buffer::New(napi_env env, size_t length); ``` - `[in] env`: The environment in which to create the `Napi::Buffer` object. @@ -28,7 +28,7 @@ collection this overload is only suitable for data which is static and never needs to be freed. ```cpp -static Napi::Buffer New(napi_env env, T* data, size_t length); +static Napi::Buffer Napi::Buffer::New(napi_env env, T* data, size_t length); ``` - `[in] env`: The environment in which to create the `Napi::Buffer` object. @@ -47,7 +47,7 @@ to be valid for the lifetime of the object. The data can only be freed once the ```cpp template -static Napi::Buffer New(napi_env env, +static Napi::Buffer Napi::Buffer::New(napi_env env, T* data, size_t length, Finalizer finalizeCallback); @@ -72,7 +72,7 @@ valid for the lifetime of the object. The data can only be freed once the ```cpp template -static Napi::Buffer New(napi_env env, +static Napi::Buffer Napi::Buffer::New(napi_env env, T* data, size_t length, Finalizer finalizeCallback, @@ -95,7 +95,7 @@ Returns a new `Napi::Buffer` object. Allocates a new `Napi::Buffer` object and copies the provided external data into it. ```cpp -static Napi::Buffer Copy(napi_env env, const T* data, size_t length); +static Napi::Buffer Napi::Buffer::Copy(napi_env env, const T* data, size_t length); ``` - `[in] env`: The environment in which to create the `Napi::Buffer` object. @@ -109,7 +109,7 @@ Returns a new `Napi::Buffer` object containing a copy of the data. Initializes an empty instance of the `Napi::Buffer` class. ```cpp -Buffer(); +Napi::Buffer::Buffer(); ``` ### Constructor @@ -117,7 +117,7 @@ Buffer(); Initializes the `Napi::Buffer` object using an existing Uint8Array. ```cpp -Buffer(napi_env env, napi_value value); +Napi::Buffer::Buffer(napi_env env, napi_value value); ``` - `[in] env`: The environment in which to create the `Napi::Buffer` object. @@ -126,7 +126,7 @@ Buffer(napi_env env, napi_value value); ### Data ```cpp -T* Data() const; +T* Napi::Buffer::Data() const; ``` Returns a pointer the external data. @@ -134,7 +134,7 @@ Returns a pointer the external data. ### Length ```cpp -size_t Length() const; +size_t Napi::Buffer::Length() const; ``` Returns the number of `T` elements in the external data. diff --git a/doc/callbackinfo.md b/doc/callbackinfo.md index d00ec3e23..af5d6b7d5 100644 --- a/doc/callbackinfo.md +++ b/doc/callbackinfo.md @@ -13,7 +13,7 @@ The `SetData` and `Data` methods are used to set and retrieve the data pointer c ### Constructor ```cpp -CallbackInfo(napi_env env, napi_callback_info info); +Napi::CallbackInfo::CallbackInfo(napi_env env, napi_callback_info info); ``` - `[in] env`: The `napi_env` environment in which to construct the `Napi::CallbackInfo` object. @@ -22,7 +22,7 @@ CallbackInfo(napi_env env, napi_callback_info info); ### Env ```cpp -Napi::Env Env() const; +Napi::Env Napi::CallbackInfo::Env() const; ``` Returns the `Env` object in which the request is being made. @@ -30,7 +30,7 @@ Returns the `Env` object in which the request is being made. ### NewTarget ```cpp -Napi::Value NewTarget() const; +Napi::Value Napi::CallbackInfo::NewTarget() const; ``` Returns the `new.target` value of the constructor call. If the function that was invoked (and for which the `Napi::NCallbackInfo` was passed) is not a constructor call, a call to `IsEmpty()` on the returned value returns true. @@ -38,7 +38,7 @@ Returns the `new.target` value of the constructor call. If the function that was ### IsConstructCall ```cpp -bool IsConstructCall() const; +bool Napi::CallbackInfo::IsConstructCall() const; ``` Returns a `bool` indicating if the function that was invoked (and for which the `Napi::CallbackInfo` was passed) is a constructor call. @@ -46,7 +46,7 @@ Returns a `bool` indicating if the function that was invoked (and for which the ### Length ```cpp -size_t Length() const; +size_t Napi::CallbackInfo::Length() const; ``` Returns the number of arguments passed in the `Napi::CallbackInfo` object. @@ -64,7 +64,7 @@ Returns a `Napi::Value` object containing the requested argument. ### This ```cpp -Napi::Value This() const; +Napi::Value Napi::CallbackInfo::This() const; ``` Returns the JavaScript `this` value for the call @@ -72,7 +72,7 @@ Returns the JavaScript `this` value for the call ### Data ```cpp -void* Data() const; +void* Napi::CallbackInfo::Data() const; ``` Returns the data pointer for the callback. @@ -80,7 +80,7 @@ Returns the data pointer for the callback. ### SetData ```cpp -void SetData(void* data); +void Napi::CallbackInfo::SetData(void* data); ``` - `[in] data`: The new data pointer to associate with this `Napi::CallbackInfo` object. @@ -90,7 +90,7 @@ Returns `void`. ### Not documented here ```cpp -~CallbackInfo(); +Napi::CallbackInfo::~CallbackInfo(); // Disallow copying to prevent multiple free of _dynamicArgs CallbackInfo(CallbackInfo const &) = delete; void operator=(CallbackInfo const &) = delete; diff --git a/doc/env.md b/doc/env.md index 1c877bb0f..9bde741ca 100644 --- a/doc/env.md +++ b/doc/env.md @@ -9,7 +9,7 @@ The Env object is usually created and passed by the Node.js runtime or node-addo ### Constructor ```cpp -Env(napi_env env); +Napi::Env::Env(napi_env env); ``` - `[in] env`: The `napi_env` environment from which to construct the `Napi::Env` object. @@ -25,7 +25,7 @@ Returns the `napi_env` opaque data structure representing the environment. ### Global ```cpp -Napi::Object Global() const; +Napi::Object Napi::Env::Global() const; ``` Returns the `Napi::Object` representing the environment's JavaScript Global Object. @@ -33,7 +33,7 @@ Returns the `Napi::Object` representing the environment's JavaScript Global Obje ### Undefined ```cpp -Napi::Value Undefined() const; +Napi::Value Napi::Env::Undefined() const; ``` Returns the `Napi::Value` representing the environment's JavaScript Undefined Object. @@ -41,7 +41,7 @@ Returns the `Napi::Value` representing the environment's JavaScript Undefined Ob ### Null ```cpp -Napi::Value Null() const; +Napi::Value Napi::Env::Null() const; ``` Returns the `Napi::Value` representing the environment's JavaScript Null Object. @@ -49,7 +49,7 @@ Returns the `Napi::Value` representing the environment's JavaScript Null Object. ### IsExceptionPending ```cpp -bool IsExceptionPending() const; +bool Napi::Env::IsExceptionPending() const; ``` Returns a `bool` indicating if an exception is pending in the environment. @@ -57,7 +57,7 @@ Returns a `bool` indicating if an exception is pending in the environment. ### GetAndClearPendingException ```cpp -Error GetAndClearPendingException(); +Napi::Error Napi::Env::GetAndClearPendingException(); ``` Returns an `Napi::Error` object representing the environment's pending exception, if any. diff --git a/doc/error.md b/doc/error.md index 4ab7d2026..b6218ebcd 100644 --- a/doc/error.md +++ b/doc/error.md @@ -20,7 +20,7 @@ For more details about error handling refer to the section titled [Error handlin Creates empty instance of an `Napi::Error` object for the specified environment. ```cpp -Error::New(Napi:Env env); +Napi::Error::New(Napi:Env env); ``` - `[in] env`: The environment in which to construct the `Napi::Error` object. @@ -32,7 +32,7 @@ Returns an instance of `Napi::Error` object. Creates instance of an `Napi::Error` object. ```cpp -Error::New(Napi:Env env, const char* message); +Napi::Error::New(Napi:Env env, const char* message); ``` - `[in] env`: The environment in which to construct the `Napi::Error` object. @@ -45,7 +45,7 @@ Returns instance of an `Napi::Error` object. Creates instance of an `Napi::Error` object ```cpp -Error::New(Napi:Env env, const std::string& message); +Napi::Error::New(Napi:Env env, const std::string& message); ``` - `[in] env`: The environment in which to construct the `Napi::Error` object. @@ -59,7 +59,7 @@ In case of an unrecoverable error in a native module, a fatal error can be throw to immediately terminate the process. ```cpp -static NAPI_NO_RETURN void Fatal(const char* location, const char* message); +static NAPI_NO_RETURN void Napi::Error::Fatal(const char* location, const char* message); ``` The function call does not return, the process will be terminated. @@ -69,7 +69,7 @@ The function call does not return, the process will be terminated. Creates empty instance of an `Napi::Error`. ```cpp -Error(); +Napi::Error::Error(); ``` Returns an instance of `Napi::Error` object. @@ -79,7 +79,7 @@ Returns an instance of `Napi::Error` object. Initializes an `Napi::Error` instance from an existing JavaScript error object. ```cpp -Error(napi_env env, napi_value value); +Napi::Error::Error(napi_env env, napi_value value); ``` - `[in] env`: The environment in which to construct the error object. @@ -90,7 +90,7 @@ Returns instance of an `Napi::Error` object. ### Message ```cpp -std::string& Message() const NAPI_NOEXCEPT; +std::string& Napi::Error::Message() const NAPI_NOEXCEPT; ``` Returns the reference to the string that represent the message of the error. @@ -100,7 +100,7 @@ Returns the reference to the string that represent the message of the error. Throw the error as JavaScript exception. ```cpp -void ThrowAsJavaScriptException() const; +void Napi::Error::ThrowAsJavaScriptException() const; ``` Throws the error as a JavaScript exception. @@ -108,7 +108,7 @@ Throws the error as a JavaScript exception. ### what ```cpp -const char* what() const NAPI_NOEXCEPT override; +const char* Napi::Error::what() const NAPI_NOEXCEPT override; ``` Returns a pointer to a null-terminated string that is used to identify the diff --git a/doc/escapable_handle_scope.md b/doc/escapable_handle_scope.md index 7dedb942f..20cbd5763 100644 --- a/doc/escapable_handle_scope.md +++ b/doc/escapable_handle_scope.md @@ -20,7 +20,7 @@ For more details refer to the section titled Creates a new escapable handle scope. ```cpp -Napi::EscapableHandleScope EscapableHandleScope::New(Napi:Env env); +Napi::EscapableHandleScope Napi::EscapableHandleScope::New(Napi:Env env); ``` - `[in] Env`: The environment in which to construct the `Napi::EscapableHandleScope` object. @@ -32,7 +32,7 @@ Returns a new `Napi::EscapableHandleScope` Creates a new escapable handle scope. ```cpp -Napi::EscapableHandleScope EscapableHandleScope::New(napi_env env, napi_handle_scope scope); +Napi::EscapableHandleScope Napi::EscapableHandleScope::New(napi_env env, napi_handle_scope scope); ``` - `[in] env`: napi_env in which the scope passed in was created. @@ -45,7 +45,7 @@ to mix usage of the C N-API and node-addon-api. operator EscapableHandleScope::napi_escapable_handle_scope ```cpp -operator EscapableHandleScope::napi_escapable_handle_scope() const +operator Napi::EscapableHandleScope::napi_escapable_handle_scope() const ``` Returns the N-API napi_escapable_handle_scope wrapped by the `Napi::EscapableHandleScope` object. @@ -54,7 +54,7 @@ the class to be used be converted to a napi_escapable_handle_scope. ### Destructor ```cpp -~EscapableHandleScope(); +Napi::EscapableHandleScope::~EscapableHandleScope(); ``` Deletes the `Napi::EscapableHandleScope` instance and allows any objects/handles created @@ -64,7 +64,7 @@ guarantee as to when the gargbage collector will do this. ### Escape ```cpp -napi::Value EscapableHandleScope::Escape(napi_value escapee); +napi::Value Napi::EscapableHandleScope::Escape(napi_value escapee); ``` - `[in] escapee`: Napi::Value or napi_env to promote to the outer scope @@ -76,7 +76,7 @@ more than once an exception will be thrown. ### Env ```cpp -Napi::Env Env() const; +Napi::Env Napi::EscapableHandleScope::Env() const; ``` Returns the `Napi:Env` associated with the `Napi::EscapableHandleScope`. diff --git a/doc/external.md b/doc/external.md index 14139aa85..4022b61dd 100644 --- a/doc/external.md +++ b/doc/external.md @@ -10,7 +10,7 @@ The `Napi::External` template class implements the ability to create a `Napi::Va ```cpp template -static Napi::External New(napi_env env, T* data); +static Napi::External Napi::External::New(napi_env env, T* data); ``` - `[in] env`: The `napi_env` environment in which to construct the `Napi::External` object. @@ -22,7 +22,7 @@ Returns the created `Napi::External` object. ```cpp template -static Napi::External New(napi_env env, +static Napi::External Napi::External::New(napi_env env, T* data, Finalizer finalizeCallback); ``` @@ -37,7 +37,7 @@ Returns the created `Napi::External` object. ```cpp template -static Napi::External New(napi_env env, +static Napi::External Napi::External::New(napi_env env, T* data, Finalizer finalizeCallback, Hint* finalizeHint); @@ -53,7 +53,7 @@ Returns the created `Napi::External` object. ### Data ```cpp -T* Data() const; +T* Napi::External::Data() const; ``` Returns a pointer to the arbitrary C++ data held by the `Napi::External` object. diff --git a/doc/function.md b/doc/function.md index 22d0b71a6..4931d6106 100644 --- a/doc/function.md +++ b/doc/function.md @@ -54,7 +54,7 @@ on the stack (for example when running a native method called from JavaScript). Creates a new empty instance of `Napi::Function`. ```cpp -Function(); +Napi::Function::Function(); ``` ### Constructor @@ -62,7 +62,7 @@ Function(); Creates a new instance of the `Napi::Function` object. ```cpp -Function(napi_env env, napi_value value); +Napi::Function::Function(napi_env env, napi_value value); ``` - `[in] env`: The `napi_env` environment in which to construct the `Napi::Function` object. @@ -76,7 +76,7 @@ Creates an instance of a `Napi::Function` object. ```cpp template -static Napi::Function New(napi_env env, Callable cb, const char* utf8name = nullptr, void* data = nullptr); +static Napi::Function Napi::Function::New(napi_env env, Callable cb, const char* utf8name = nullptr, void* data = nullptr); ``` - `[in] env`: The `napi_env` environment in which to construct the `Napi::Function` object. @@ -91,7 +91,7 @@ Returns an instance of a `Napi::Function` object. ```cpp template -static Napi::Function New(napi_env env, Callable cb, const std::string& utf8name, void* data = nullptr); +static Napi::Function Napi::Function::New(napi_env env, Callable cb, const std::string& utf8name, void* data = nullptr); ``` - `[in] env`: The `napi_env` environment in which to construct the `Napi::Function` object. @@ -108,7 +108,7 @@ Creates a new JavaScript value from one that represents the constructor for the object. ```cpp -Napi::Object New(const std::initializer_list& args) const; +Napi::Object Napi::Function::New(const std::initializer_list& args) const; ``` - `[in] args`: Initializer list of JavaScript values as `napi_value` representing @@ -122,7 +122,7 @@ Creates a new JavaScript value from one that represents the constructor for the object. ```cpp -Napi::Object New(const std::vector& args) const; +Napi::Object Napi::Function::New(const std::vector& args) const; ``` - `[in] args`: Vector of JavaScript values as `napi_value` representing the @@ -136,7 +136,7 @@ Creates a new JavaScript value from one that represents the constructor for the object. ```cpp -Napi::Object New(size_t argc, const napi_value* args) const; +Napi::Object Napi::Function::New(size_t argc, const napi_value* args) const; ``` - `[in] argc`: The number of the arguments passed to the contructor function. @@ -150,7 +150,7 @@ Returns a new JavaScript object. Calls a Javascript function from a native add-on. ```cpp -Napi::Value Call(const std::initializer_list& args) const; +Napi::Value Napi::Function::Call(const std::initializer_list& args) const; ``` - `[in] args`: Initializer list of JavaScript values as `napi_value` representing @@ -163,7 +163,7 @@ Returns a `Napi::Value` representing the JavaScript value returned by the functi Calls a JavaScript function from a native add-on. ```cpp -Napi::Value Call(const std::vector& args) const; +Napi::Value Napi::Function::Call(const std::vector& args) const; ``` - `[in] args`: Vector of JavaScript values as `napi_value` representing the @@ -176,7 +176,7 @@ Returns a `Napi::Value` representing the JavaScript value returned by the functi Calls a Javascript function from a native add-on. ```cpp -Napi::Value Call(size_t argc, const napi_value* args) const; +Napi::Value Napi::Function::Call(size_t argc, const napi_value* args) const; ``` - `[in] argc`: The number of the arguments passed to the function. @@ -190,7 +190,7 @@ Returns a `Napi::Value` representing the JavaScript value returned by the functi Calls a Javascript function from a native add-on. ```cpp -Napi::Value Call(napi_value recv, const std::initializer_list& args) const; +Napi::Value Napi::Function::Call(napi_value recv, const std::initializer_list& args) const; ``` - `[in] recv`: The `this` object passed to the called function. @@ -204,7 +204,7 @@ Returns a `Napi::Value` representing the JavaScript value returned by the functi Calls a Javascript function from a native add-on. ```cpp -Napi::Value Call(napi_value recv, const std::vector& args) const; +Napi::Value Napi::Function::Call(napi_value recv, const std::vector& args) const; ``` - `[in] recv`: The `this` object passed to the called function. @@ -218,7 +218,7 @@ Returns a `Napi::Value` representing the JavaScript value returned by the functi Calls a Javascript function from a native add-on. ```cpp -Napi::Value Call(napi_value recv, size_t argc, const napi_value* args) const; +Napi::Value Napi::Function::Call(napi_value recv, size_t argc, const napi_value* args) const; ``` - `[in] recv`: The `this` object passed to the called function. @@ -233,7 +233,7 @@ Returns a `Napi::Value` representing the JavaScript value returned by the functi Calls a Javascript function from a native add-on after an asynchronous operation. ```cpp -Napi::Value MakeCallback(napi_value recv, const std::initializer_list& args) const; +Napi::Value Napi::Function::MakeCallback(napi_value recv, const std::initializer_list& args) const; ``` - `[in] recv`: The `this` object passed to the called function. @@ -247,7 +247,7 @@ Returns a `Napi::Value` representing the JavaScript value returned by the functi Calls a Javascript function from a native add-on after an asynchronous operation. ```cpp -Napi::Value MakeCallback(napi_value recv, const std::vector& args) const; +Napi::Value Napi::Function::MakeCallback(napi_value recv, const std::vector& args) const; ``` - `[in] recv`: The `this` object passed to the called function. @@ -261,7 +261,7 @@ Returns a `Napi::Value` representing the JavaScript value returned by the functi Calls a Javascript function from a native add-on after an asynchronous operation. ```cpp -Napi::Value MakeCallback(napi_value recv, size_t argc, const napi_value* args) const; +Napi::Value Napi::Function::MakeCallback(napi_value recv, size_t argc, const napi_value* args) const; ``` - `[in] recv`: The `this` object passed to the called function. diff --git a/doc/function_reference.md b/doc/function_reference.md index 1462aefc8..44998d7ae 100644 --- a/doc/function_reference.md +++ b/doc/function_reference.md @@ -23,7 +23,7 @@ Creates a "weak" reference to the value, in that the initial reference count is set to 0. ```cpp -static Napi::FunctionReference Weak(const Function& value); +static Napi::FunctionReference Napi::FunctionReference::Weak(const Napi::Function& value); ``` - `[in] value`: The value which is to be referenced. @@ -36,7 +36,7 @@ Creates a "persistent" reference to the value, in that the initial reference count is set to 1. ```cpp -static Napi::FunctionReference Persistent(const Function& value); +static Napi::FunctionReference Napi::FunctionReference::Persistent(const Napi::Function& value); ``` - `[in] value`: The value which is to be referenced. @@ -48,7 +48,7 @@ Returns the newly created reference. Creates a new empty instance of `Napi::FunctionReference`. ```cpp -FunctionReference(); +Napi::FunctionReference::FunctionReference(); ``` ### Constructor @@ -56,7 +56,7 @@ FunctionReference(); Creates a new instance of the `Napi::FunctionReference`. ```cpp -FunctionReference(napi_env env, napi_ref ref); +Napi::FunctionReference::FunctionReference(napi_env env, napi_ref ref); ``` - `[in] env`: The environment in which to construct the `Napi::FunctionReference` object. @@ -69,7 +69,7 @@ Returns a newly created `Napi::FunctionReference` object. Constructs a new instance by calling the constructor held by this reference. ```cpp -Napi::Object New(const std::initializer_list& args) const; +Napi::Object Napi::FunctionReference::New(const std::initializer_list& args) const; ``` - `[in] args`: Initializer list of JavaScript values as `napi_value` representing @@ -82,7 +82,7 @@ Returns a new JavaScript object. Constructs a new instance by calling the constructor held by this reference. ```cpp -Napi::Object New(const std::vector& args) const; +Napi::Object Napi::FunctionReference::New(const std::vector& args) const; ``` - `[in] args`: Vector of JavaScript values as `napi_value` representing the @@ -95,7 +95,7 @@ Returns a new JavaScript object. Calls a referenced Javascript function from a native add-on. ```cpp -Napi::Value Call(const std::initializer_list& args) const; +Napi::Value Napi::FunctionReference::Call(const std::initializer_list& args) const; ``` - `[in] args`: Initializer list of JavaScript values as `napi_value` representing @@ -109,7 +109,7 @@ function. Calls a referenced Javascript function from a native add-on. ```cpp -Napi::Value Call(const std::vector& args) const; +Napi::Value Napi::FunctionReference::Call(const std::vector& args) const; ``` - `[in] args`: Vector of JavaScript values as `napi_value` representing the @@ -123,7 +123,7 @@ function. Calls a referenced Javascript function from a native add-on. ```cpp -Napi::Value Call(napi_value recv, const std::initializer_list& args) const; +Napi::Value Napi::FunctionReference::Call(napi_value recv, const std::initializer_list& args) const; ``` - `[in] recv`: The `this` object passed to the referenced function when it's called. @@ -138,7 +138,7 @@ function. Calls a referenced Javascript function from a native add-on. ```cpp -Napi::Value Call(napi_value recv, const std::vector& args) const; +Napi::Value Napi::FunctionReference::Call(napi_value recv, const std::vector& args) const; ``` - `[in] recv`: The `this` object passed to the referenced function when it's called. @@ -154,7 +154,7 @@ Calls a referenced Javascript function from a native add-on after an asynchronou operation. ```cpp -Napi::Value MakeCallback(napi_value recv, const std::initializer_list& args) const; +Napi::Value Napi::FunctionReference::MakeCallback(napi_value recv, const std::initializer_list& args) const; ``` - `[in] recv`: The `this` object passed to the referenced function when it's called. @@ -170,7 +170,7 @@ Calls a referenced Javascript function from a native add-on after an asynchronou operation. ```cpp -Napi::Value MakeCallback(napi_value recv, const std::vector& args) const; +Napi::Value Napi::FunctionReference::MakeCallback(napi_value recv, const std::vector& args) const; ``` - `[in] recv`: The `this` object passed to the referenced function when it's called. diff --git a/doc/handle_scope.md b/doc/handle_scope.md index a410d515f..f06f87bc8 100644 --- a/doc/handle_scope.md +++ b/doc/handle_scope.md @@ -15,7 +15,7 @@ the section titled [Object lifetime management](object_lifetime_management.md). Creates a new handle scope on the stack. ```cpp -HandleScope(Napi:Env env); +Napi::HandleScope::HandleScope(Napi:Env env); ``` - `[in] env`: The environment in which to construct the `Napi::HandleScope` object. @@ -27,7 +27,7 @@ Returns a new `Napi::HandleScope` Creates a new handle scope on the stack. ```cpp -HandleScope(Napi::Env env, Napi::HandleScope scope); +Napi::HandleScope::HandleScope(Napi::Env env, Napi::HandleScope scope); ``` - `[in] env`: `Napi::Env` in which the scope passed in was created. @@ -40,7 +40,7 @@ and node-addon-api. operator HandleScope::napi_handle_scope ```cpp -operator napi_handle_scope() const +operator Napi::HandleScope::napi_handle_scope() const ``` Returns the N-API napi_handle_scope wrapped by the `Napi::EscapableHandleScope` object. @@ -49,7 +49,7 @@ the class to be used be converted to a napi_handle_scope. ### Destructor ```cpp -~HandleScope(); +Napi::HandleScope::~HandleScope(); ``` Deletes the `Napi::HandleScope` instance and allows any objects/handles created @@ -59,7 +59,7 @@ guarantee as to when the gargbage collector will do this. ### Env ```cpp -Napi::Env Env() const; +Napi::Env Napi::HandleScope::Env() const; ``` Returns the `Napi:Env` associated with the `Napi::HandleScope`. diff --git a/doc/number.md b/doc/number.md index 0d01b26b5..d1bee4810 100644 --- a/doc/number.md +++ b/doc/number.md @@ -12,16 +12,16 @@ Napi::Number::New(Napi::Env env, double value); - `[in] value`: The value the Javascript Number will contain ```cpp -Napi::Number(); +Napi::Number::Number(); ``` returns a new empty Javascript Number You can easily cast a Javascript number to one of: - - int32_t - - uint32_t - - int64_t - - float - - double + - `int32_t` + - `uint32_t` + - `int64_t` + - `float` + - `double` The following shows an example of casting a number to an uint32_t value. diff --git a/doc/object_reference.md b/doc/object_reference.md index fd8c38f6b..1773296e1 100644 --- a/doc/object_reference.md +++ b/doc/object_reference.md @@ -30,7 +30,7 @@ void Init(Env env) { ### Initialization ```cpp -static Napi::ObjectReference New(const Object& value, uint32_t initialRefcount = 0); +static Napi::ObjectReference Napi::ObjectReference::New(const Object& value, uint32_t initialRefcount = 0); ``` * `[in] value`: The `Napi::Object` which is to be referenced. @@ -40,7 +40,7 @@ static Napi::ObjectReference New(const Object& value, uint32_t initialRefcount = Returns the newly created reference. ```cpp -static Napi::ObjectReference Weak(const Object& value); +static Napi::ObjectReference Napi::ObjectReference::Weak(const Object& value); ``` Creates a "weak" reference to the value, in that the initial count of number of references is set to 0. @@ -50,7 +50,7 @@ Creates a "weak" reference to the value, in that the initial count of number of Returns the newly created reference. ```cpp -static Napi::ObjectReference Persistent(const Object& value); +static Napi::ObjectReference Napi::ObjectReference::Persistent(const Object& value); ``` Creates a "persistent" reference to the value, in that the initial count of number of references is set to 1. @@ -62,7 +62,7 @@ Returns the newly created reference. ### Empty Constructor ```cpp -ObjectReference(); +Napi::ObjectReference::ObjectReference(); ``` Returns a new _empty_ `Napi::ObjectReference` instance. @@ -70,7 +70,7 @@ Returns a new _empty_ `Napi::ObjectReference` instance. ### Constructor ```cpp -ObjectReference(napi_env env, napi_value value); +Napi::ObjectReference::ObjectReference(napi_env env, napi_value value); ``` * `[in] env`: The `napi_env` environment in which to construct the `Napi::ObjectReference` object. @@ -81,7 +81,7 @@ Returns the newly created reference. ### Set ```cpp -void Set(___ key, ___ value); +void Napi::ObjectReference::Set(___ key, ___ value); ``` * `[in] key`: The name for the property being assigned. @@ -103,7 +103,7 @@ The `value` can be any of the following types: ### Get ```cpp -Napi::Value Get(___ key); +Napi::Value Napi::ObjectReference::Get(___ key); ``` * `[in] key`: The name of the property to return the value for. diff --git a/doc/promises.md b/doc/promises.md index c08b64a1a..bd23a51d5 100644 --- a/doc/promises.md +++ b/doc/promises.md @@ -24,7 +24,7 @@ Later, when the asynchronous process completes, call either the `Resolve` or `Re ### Factory Method ```cpp -static Napi::Promise::Deferred Promise::Deferred::New(napi_env env); +static Napi::Promise::Deferred Napi::Promise::Deferred::New(napi_env env); ``` * `[in] env`: The `napi_env` environment in which to create the `Napi::Promise::Deferred` object. @@ -32,7 +32,7 @@ static Napi::Promise::Deferred Promise::Deferred::New(napi_env env); ### Constructor ```cpp -Promise::Deferred(napi_env env); +Napi::Promise::Deferred(napi_env env); ``` * `[in] env`: The `napi_env` environment in which to construct the `Napi::Promise::Deferred` object. @@ -40,7 +40,7 @@ Promise::Deferred(napi_env env); ### Env ```cpp -Napi::Env Env() const; +Napi::Env Napi::Promise::Deferred::Env() const; ``` Returns the Env environment this `Napi::Promise::Deferred` object is associated with. @@ -48,7 +48,7 @@ Returns the Env environment this `Napi::Promise::Deferred` object is associated ### Promise ```cpp -Napi::Promise Promise::Deferred::Promise() const; +Napi::Promise Napi::Promise::Deferred::Promise() const; ``` Returns the `Napi::Promise` object held by the `Napi::Promise::Deferred` object. @@ -56,7 +56,7 @@ Returns the `Napi::Promise` object held by the `Napi::Promise::Deferred` object. ### Resolve ```cpp -void Promise::Deferred::Resolve(napi_value value) const; +void Napi::Promise::Deferred::Resolve(napi_value value) const; ``` Resolves the `Napi::Promise` object held by the `Napi::Promise::Deferred` object. @@ -66,7 +66,7 @@ Resolves the `Napi::Promise` object held by the `Napi::Promise::Deferred` object ### Reject ```cpp -void Promise::Deferred::Reject(napi_value value) const; +void Napi::Promise::Deferred::Reject(napi_value value) const; ``` Rejects the Promise object held by the `Napi::Promise::Deferred` object. diff --git a/doc/range_error.md b/doc/range_error.md index c1c682367..adefb96cb 100644 --- a/doc/range_error.md +++ b/doc/range_error.md @@ -16,7 +16,7 @@ For more details about error handling refer to the section titled [Error handlin Creates a new instance of a `Napi::RangeError` object. ```cpp -RangeError::New(Napi:Env env, const char* message); +Napi::RangeError::New(Napi:Env env, const char* message); ``` - `[in] Env`: The environment in which to construct the `Napi::RangeError` object. @@ -29,7 +29,7 @@ Returns an instance of a `Napi::RangeError` object. Creates a new instance of a `Napi::RangeError` object. ```cpp -RangeError::New(Napi:Env env, const std::string& message); +Napi::RangeError::New(Napi:Env env, const std::string& message); ``` - `[in] Env`: The environment in which to construct the `Napi::RangeError` object. @@ -42,7 +42,7 @@ Returns an instance of a `Napi::RangeError` object. Creates a new empty instance of a `Napi::RangeError`. ```cpp -RangeError(); +Napi::RangeError::RangeError(); ``` ### Constructor @@ -50,7 +50,7 @@ RangeError(); Initializes a `Napi::RangeError` instance from an existing Javascript error object. ```cpp -RangeError(napi_env env, napi_value value); +Napi::RangeError::RangeError(napi_env env, napi_value value); ``` - `[in] Env`: The environment in which to construct the `Napi::RangeError` object. diff --git a/doc/reference.md b/doc/reference.md index f5f1bd972..108c009bb 100644 --- a/doc/reference.md +++ b/doc/reference.md @@ -17,7 +17,7 @@ The following classes inherit, either directly or indirectly, from `Napi::Refere ### Factory Method ```cpp -static Napi::Reference New(const T& value, uint32_t initialRefcount = 0); +static Napi::Reference Napi::Reference::New(const T& value, uint32_t initialRefcount = 0); ``` * `[in] value`: The value which is to be referenced. @@ -27,7 +27,7 @@ static Napi::Reference New(const T& value, uint32_t initialRefcount = 0); ### Empty Constructor ```cpp -Reference(); +Napi::Reference::Reference(); ``` Creates a new _empty_ `Napi::Reference` instance. @@ -35,7 +35,7 @@ Creates a new _empty_ `Napi::Reference` instance. ### Constructor ```cpp -Reference(napi_env env, napi_value value); +Napi::Reference::Reference(napi_env env, napi_value value); ``` * `[in] env`: The `napi_env` environment in which to construct the `Napi::Reference` object. @@ -45,7 +45,7 @@ Reference(napi_env env, napi_value value); ### Env ```cpp -Napi::Env Env() const; +Napi::Env Napi::Reference::Env() const; ``` Returns the `Napi::Env` value in which the `Napi::Reference` was instantiated. @@ -53,7 +53,7 @@ Returns the `Napi::Env` value in which the `Napi::Reference` was instantiated. ### IsEmpty ```cpp -bool IsEmpty() const; +bool Napi::Reference::IsEmpty() const; ``` Determines whether the value held by the `Napi::Reference` is empty. @@ -61,7 +61,7 @@ Determines whether the value held by the `Napi::Reference` is empty. ### Value ```cpp -T Value() const; +T Napi::Reference::Value() const; ``` Returns the value held by the `Napi::Reference`. @@ -69,7 +69,7 @@ Returns the value held by the `Napi::Reference`. ### Ref ```cpp -uint32_t Ref(); +uint32_t Napi::Reference::Ref(); ``` Increments the reference count for the `Napi::Reference` and returns the resulting reference count. Throws an error if the increment fails. @@ -77,7 +77,7 @@ Increments the reference count for the `Napi::Reference` and returns the resulti ### Unref ```cpp -uint32_t Unref(); +uint32_t Napi::Reference::Unref(); ``` Decrements the reference count for the `Napi::Reference` and returns the resulting reference count. Throws an error if the decrement fails. @@ -85,7 +85,7 @@ Decrements the reference count for the `Napi::Reference` and returns the resulti ### Reset (Empty) ```cpp -void Reset(); +void Napi::Reference::Reset(); ``` Sets the value held by the `Napi::Reference` to be empty. @@ -93,7 +93,7 @@ Sets the value held by the `Napi::Reference` to be empty. ### Reset ```cpp -void Reset(const T& value, uint32_t refcount = 0); +void Napi::Reference::Reset(const T& value, uint32_t refcount = 0); ``` * `[in] value`: The value which is to be referenced. @@ -105,7 +105,7 @@ Sets the value held by the `Napi::Reference`. ### SuppressDestruct ```cpp -void SuppressDestruct(); +void Napi::Reference::SuppressDestruct(); ``` Call this method on a `Napi::Reference` that is declared as static data to prevent its destructor, running at program shutdown time, from attempting to reset the reference when the environment is no longer valid. diff --git a/doc/string.md b/doc/string.md index 14a33e4e9..874d3d4db 100644 --- a/doc/string.md +++ b/doc/string.md @@ -3,7 +3,7 @@ ## Constructor ```cpp -String(); +Napi::String::String(); ``` Returns a new **empty** `Napi::String` instance. @@ -13,7 +13,7 @@ being used, callers should check the result of `Env::IsExceptionPending` before attempting to use the returned value. ```cpp -String(napi_env env, napi_value value); ///< Wraps a N-API value primitive. +Napi::String::String(napi_env env, napi_value value); ///< Wraps a N-API value primitive. ``` - `[in] env` - The environment in which to create the string. - `[in] value` - The primitive to wrap. @@ -45,17 +45,17 @@ Returns a UTF-16 encoded C++ string. ### New ```cpp -String::New(); +Napi::String::New(); ``` Returns a new empty `Napi::String`. ### New ```cpp -String::New(napi_env env, const std::string& value); -String::New(napi_env env, const std::u16string& value); -String::New(napi_env env, const char* value); -String::New(napi_env env, const char16_t* value); +Napi::String::New(napi_env env, const std::Napi::string& value); +Napi::String::New(napi_env env, const std::u16Napi::string& value); +Napi::String::New(napi_env env, const char* value); +Napi::String::New(napi_env env, const char16_t* value); ``` - `[in] env`: The `napi_env` environment in which to construct the `Napi::Value` object. @@ -73,14 +73,14 @@ attempting to use the returned value. ### Utf8Value ```cpp -std::string Utf8Value() const; +std::string Napi::String::Utf8Value() const; ``` Returns a UTF-8 encoded C++ string. ### Utf16Value ```cpp -std::u16string Utf16Value() const; +std::u16string Napi::String::Utf16Value() const; ``` Returns a UTF-16 encoded C++ string. diff --git a/doc/symbol.md b/doc/symbol.md index 3330efd41..0fb37fb7e 100644 --- a/doc/symbol.md +++ b/doc/symbol.md @@ -7,17 +7,17 @@ Instantiates a new `Napi::Symbol` value. ```cpp -Symbol(); +Napi::Symbol::Symbol(); ``` Returns a new empty `Napi::Symbol`. ### New ```cpp -Symbol::New(napi_env env, const std::string& description); -Symbol::New(napi_env env, const char* description); -Symbol::New(napi_env env, String description); -Symbol::New(napi_env env, napi_value description); +Napi::Symbol::New(napi_env env, const std::string& description); +Napi::Symbol::New(napi_env env, const char* description); +Napi::Symbol::New(napi_env env, String description); +Napi::Symbol::New(napi_env env, napi_value description); ``` - `[in] env`: The `napi_env` environment in which to construct the `Napi::Symbol` object. @@ -34,10 +34,10 @@ attempting to use the returned value. ### Utf8Value ```cpp -static Napi::Symbol WellKnown(napi_env env, const std::string& name); +static Napi::Symbol Napi::Symbol::WellKnown(napi_env env, const std::string& name); ``` -- `[in] env`: The `napi_env` environment in which to construct the Symbol object. +- `[in] env`: The `napi_env` environment in which to construct the `Napi::Symbol` object. - `[in] name`: The C++ string representing the `Napi::Symbol` to retrieve. Returns a `Napi::Symbol` representing a well-known `Symbol` from the diff --git a/doc/type_error.md b/doc/type_error.md index 28a2f7052..24bbf8eda 100644 --- a/doc/type_error.md +++ b/doc/type_error.md @@ -16,7 +16,7 @@ For more details about error handling refer to the section titled [Error handlin Creates a new instance of the `Napi::TypeError` object. ```cpp -TypeError::New(Napi:Env env, const char* message); +Napi::TypeError::New(Napi:Env env, const char* message); ``` - `[in] Env`: The environment in which to construct the `Napi::TypeError` object. @@ -29,7 +29,7 @@ Returns an instance of a `Napi::TypeError` object. Creates a new instance of a `Napi::TypeError` object. ```cpp -TypeError::New(Napi:Env env, const std::string& message); +Napi::TypeError::New(Napi:Env env, const std::string& message); ``` - `[in] Env`: The environment in which to construct the `Napi::TypeError` object. @@ -42,7 +42,7 @@ Returns an instance of a `Napi::TypeError` object. Creates a new empty instance of a `Napi::TypeError`. ```cpp -TypeError(); +Napi::TypeError::TypeError(); ``` ### Constructor @@ -50,7 +50,7 @@ TypeError(); Initializes a `Napi::TypeError` instance from an existing JavaScript error object. ```cpp -TypeError(napi_env env, napi_value value); +Napi::TypeError::TypeError(napi_env env, napi_value value); ``` - `[in] Env`: The environment in which to construct the `Napi::TypeError` object. diff --git a/doc/typed_array.md b/doc/typed_array.md index 63063aef6..ced67d8e4 100644 --- a/doc/typed_array.md +++ b/doc/typed_array.md @@ -11,7 +11,7 @@ class. Initializes an empty instance of the `Napi::TypedArray` class. ```cpp -TypedArray(); +Napi::TypedArray::TypedArray(); ``` ### Constructor @@ -19,7 +19,7 @@ TypedArray(); Initializes a wrapper instance of an existing `Napi::TypedArray` instance. ```cpp -TypedArray(napi_env env, napi_value value); +Napi::TypedArray::TypedArray(napi_env env, napi_value value); ``` - `[in] env`: The environment in which to create the `Napi::TypedArray` instance. @@ -28,7 +28,7 @@ TypedArray(napi_env env, napi_value value); ### TypedArrayType ```cpp -napi_typedarray_type TypedArrayType() const; +napi_typedarray_type Napi::TypedArray::TypedArrayType() const; ``` Returns the type of this instance. @@ -36,7 +36,7 @@ Returns the type of this instance. ### ArrayBuffer ```cpp -Napi::ArrayBuffer ArrayBuffer() const; +Napi::ArrayBuffer Napi::TypedArray::ArrayBuffer() const; ``` Returns the backing array buffer. @@ -44,7 +44,7 @@ Returns the backing array buffer. ### ElementSize ```cpp -uint8_t ElementSize() const; +uint8_t Napi::TypedArray::ElementSize() const; ``` Returns the size of one element, in bytes. @@ -52,7 +52,7 @@ Returns the size of one element, in bytes. ### ElementLength ```cpp -size_t ElementLength() const; +size_t Napi::TypedArray::ElementLength() const; ``` Returns the number of elements. @@ -60,7 +60,7 @@ Returns the number of elements. ### ByteOffset ```cpp -size_t ByteOffset() const; +size_t Napi::TypedArray::ByteOffset() const; ``` Returns the offset into the `Napi::ArrayBuffer` where the array starts, in bytes. @@ -68,7 +68,7 @@ Returns the offset into the `Napi::ArrayBuffer` where the array starts, in bytes ### ByteLength ```cpp -size_t ByteLength() const; +size_t Napi::TypedArray::ByteLength() const; ``` Returns the length of the array, in bytes. diff --git a/doc/typed_array_of.md b/doc/typed_array_of.md index f11c47bf8..c0f1ad043 100644 --- a/doc/typed_array_of.md +++ b/doc/typed_array_of.md @@ -40,7 +40,7 @@ The array type parameter can normally be omitted (because it is inferred from the template parameter T), except when creating a "clamped" array. ```cpp -static Napi::TypedArrayOf New(napi_env env, +static Napi::TypedArrayOf Napi::TypedArrayOf::New(napi_env env, size_t elementLength, napi_typedarray_type type); ``` @@ -59,7 +59,7 @@ The array `type` parameter can normally be omitted (because it is inferred from the template parameter `T`), except when creating a "clamped" array. ```cpp -static Napi::TypedArrayOf New(napi_env env, +static Napi::TypedArrayOf Napi::TypedArrayOf::New(napi_env env, size_t elementLength, Napi::ArrayBuffer arrayBuffer, size_t bufferOffset, @@ -80,7 +80,7 @@ Returns a new `Napi::TypedArrayOf` instance. Initializes an empty instance of the `Napi::TypedArrayOf` class. ```cpp -TypedArrayOf(); +Napi::TypedArrayOf::TypedArrayOf(); ``` ### Constructor @@ -88,7 +88,7 @@ TypedArrayOf(); Initializes a wrapper instance of an existing `Napi::TypedArrayOf` object. ```cpp -TypedArrayOf(napi_env env, napi_value value); +Napi::TypedArrayOf::TypedArrayOf(napi_env env, napi_value value); ``` - `[in] env`: The environment in which to create the `Napi::TypedArrayOf` object. @@ -117,7 +117,7 @@ Returns the element found at the given index. ### Data ```cpp -T* Data() const; +T* Napi::TypedArrayOf::Data() const; ``` Returns a pointer into the backing `Napi::ArrayBuffer` which is offset to point to the @@ -126,7 +126,7 @@ start of the array. ### Data ```cpp -const T* Data() const +const T* Napi::TypedArrayOf::Data() const ``` Returns a pointer into the backing `Napi::ArrayBuffer` which is offset to point to the diff --git a/doc/value.md b/doc/value.md index 716446edf..efe82a4d4 100644 --- a/doc/value.md +++ b/doc/value.md @@ -25,7 +25,7 @@ The following classes inherit, either directly or indirectly, from `Napi::Value` ### Empty Constructor ```cpp -Value(); +Napi::Value::Value(); ``` Creates a new *empty* `Napi::Value` instance. @@ -33,26 +33,26 @@ Creates a new *empty* `Napi::Value` instance. ### Constructor ```cpp -Value(napi_env env, napi_value value); +Napi::Value::Value(napi_env env, napi_value value); ``` - `[in] env`: The `napi_env` environment in which to construct the `Napi::Value` object. - `[in] value`: The C++ primitive from which to instantiate the `Napi::Value`. `value` may be any of: - - bool + - `bool` - Any integer type - Any floating point type - - const char* (encoded using UTF-8, null-terminated) - - const char16_t* (encoded using UTF-16-LE, null-terminated) - - std::string (encoded using UTF-8) - - std::u16string - - Napi::Value - - napi_value + - `const char*` (encoded using UTF-8, null-terminated) + - `const char16_t*` (encoded using UTF-16-LE, null-terminated) + - `std::string` (encoded using UTF-8) + - `std::u16string` + - `Napi::Value` + - `napi_value` ### From ```cpp -template static Napi::Value From(napi_env env, const T& value); +template static Napi::Value Napi::Value::From(napi_env env, const T& value); ``` - `[in] env`: The `napi_env` environment in which to create the `Napi::Value` object. @@ -94,7 +94,7 @@ Returns a `bool` indicating if this `Napi::Value` does not strictly equal anothe ### StrictEquals ```cpp -bool StrictEquals(const Value& other) const; +bool Napi::Value::StrictEquals(const Value& other) const; ``` - `[in] other`: The `Napi::Value` object to be compared. @@ -103,7 +103,7 @@ Returns a `bool` indicating if this `Napi::Value` strictly equals another `Napi: ### Env ```cpp -Napi::Env Env() const; +Napi::Env Napi::Value::Env() const; ``` Returns the `Napi::Env` environment this value is associated with. @@ -111,7 +111,7 @@ Returns the `Napi::Env` environment this value is associated with. ### IsEmpty ```cpp -bool IsEmpty() const; +bool Napi::Value::IsEmpty() const; ``` Returns a `bool` indicating if this `Napi::Value` is *empty* (uninitialized). @@ -124,7 +124,7 @@ When C++ exceptions are disabled at compile time, a method with a `Napi::Value` ### Type ```cpp -napi_valuetype Type() const; +napi_valuetype Napi::Value::Type() const; ``` Returns the `napi_valuetype` type of the `Napi::Value`. @@ -132,7 +132,7 @@ Returns the `napi_valuetype` type of the `Napi::Value`. ### IsUndefined ```cpp -bool IsUndefined() const; +bool Napi::Value::IsUndefined() const; ``` Returns a `bool` indicating if this `Napi::Value` is an undefined JavaScript value. @@ -140,7 +140,7 @@ Returns a `bool` indicating if this `Napi::Value` is an undefined JavaScript val ### IsNull ```cpp -bool IsNull() const; +bool Napi::Value::IsNull() const; ``` Returns a `bool` indicating if this `Napi::Value` is a null JavaScript value. @@ -148,7 +148,7 @@ Returns a `bool` indicating if this `Napi::Value` is a null JavaScript value. ### IsBoolean ```cpp -bool IsBoolean() const; +bool Napi::Value::IsBoolean() const; ``` Returns a `bool` indicating if this `Napi::Value` is a JavaScript boolean. @@ -156,7 +156,7 @@ Returns a `bool` indicating if this `Napi::Value` is a JavaScript boolean. ### IsNumber ```cpp -bool IsNumber() const; +bool Napi::Value::IsNumber() const; ``` Returns a `bool` indicating if this `Napi::Value` is a JavaScript number. @@ -164,7 +164,7 @@ Returns a `bool` indicating if this `Napi::Value` is a JavaScript number. ### IsString ```cpp -bool IsString() const; +bool Napi::Value::IsString() const; ``` Returns a `bool` indicating if this `Napi::Value` is a JavaScript string. @@ -172,7 +172,7 @@ Returns a `bool` indicating if this `Napi::Value` is a JavaScript string. ### IsSymbol ```cpp -bool IsSymbol() const; +bool Napi::Value::IsSymbol() const; ``` Returns a `bool` indicating if this `Napi::Value` is a JavaScript symbol. @@ -180,7 +180,7 @@ Returns a `bool` indicating if this `Napi::Value` is a JavaScript symbol. ### IsArray ```cpp -bool IsArray() const; +bool Napi::Value::IsArray() const; ``` Returns a `bool` indicating if this `Napi::Value` is a JavaScript array. @@ -188,7 +188,7 @@ Returns a `bool` indicating if this `Napi::Value` is a JavaScript array. ### IsArrayBuffer ```cpp -bool IsArrayBuffer() const; +bool Napi::Value::IsArrayBuffer() const; ``` Returns a `bool` indicating if this `Napi::Value` is a JavaScript array buffer. @@ -196,7 +196,7 @@ Returns a `bool` indicating if this `Napi::Value` is a JavaScript array buffer. ### IsTypedArray ```cpp -bool IsTypedArray() const; +bool Napi::Value::IsTypedArray() const; ``` Returns a `bool` indicating if this `Napi::Value` is a JavaScript typed array. @@ -204,7 +204,7 @@ Returns a `bool` indicating if this `Napi::Value` is a JavaScript typed array. ### IsObject ```cpp -bool IsObject() const; +bool Napi::Value::IsObject() const; ``` Returns a `bool` indicating if this `Napi::Value` is JavaScript object. @@ -212,7 +212,7 @@ Returns a `bool` indicating if this `Napi::Value` is JavaScript object. ### IsFunction ```cpp -bool IsFunction() const; +bool Napi::Value::IsFunction() const; ``` Returns a `bool` indicating if this `Napi::Value` is a JavaScript function. @@ -220,7 +220,7 @@ Returns a `bool` indicating if this `Napi::Value` is a JavaScript function. ### IsBuffer ```cpp -bool IsBuffer() const; +bool Napi::Value::IsBuffer() const; ``` Returns a `bool` indicating if this `Napi::Value` is a Node buffer. @@ -228,7 +228,7 @@ Returns a `bool` indicating if this `Napi::Value` is a Node buffer. ### As ```cpp -template T As() const; +template T Napi::Value::As() const; ``` Casts to another type of `Napi::Value`, when the actual type is known or assumed. @@ -238,7 +238,7 @@ This conversion does not coerce the type. Calling any methods inappropriate for ### ToBoolean ```cpp -Boolean ToBoolean() const; +Napi::Boolean Napi::Value::ToBoolean() const; ``` Returns the `Napi::Value` coerced to a JavaScript boolean. @@ -246,7 +246,7 @@ Returns the `Napi::Value` coerced to a JavaScript boolean. ### ToNumber ```cpp -Number ToNumber() const; +Napi::Number Napi::Value::ToNumber() const; ``` Returns the `Napi::Value` coerced to a JavaScript number. @@ -254,7 +254,7 @@ Returns the `Napi::Value` coerced to a JavaScript number. ### ToString ```cpp -String ToString() const; +Napi::String Napi::Value::ToString() const; ``` Returns the `Napi::Value` coerced to a JavaScript string. @@ -262,7 +262,7 @@ Returns the `Napi::Value` coerced to a JavaScript string. ### ToObject ```cpp -Object ToObject() const; +Napi::Object Napi::Value::ToObject() const; ``` Returns the `Napi::Value` coerced to a JavaScript object. From 6951c13723d10bf0cf864082f03bf6350431e351 Mon Sep 17 00:00:00 2001 From: NickNaso Date: Tue, 18 Sep 2018 00:19:30 +0200 Subject: [PATCH 4/9] Added missing part --- doc/working_with_javascript_values.md | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/doc/working_with_javascript_values.md b/doc/working_with_javascript_values.md index 0c5cbe2ee..2aee0e04a 100644 --- a/doc/working_with_javascript_values.md +++ b/doc/working_with_javascript_values.md @@ -1,5 +1,13 @@ # Working with JavaScript Values -You are reading a draft of the next documentation and it's in continuous update so -if you don't find what you need please refer to: -[C++ wrapper classes for the ABI-stable C APIs for Node.js](https://nodejs.github.io/node-addon-api/) +`node-addon-api` provides a set of classes that allow to create and manage +JavaScript object: + +- [Function](doc/function.md) + - [FunctionReference](doc/function_reference.md) +- [ObjectWrap](doc/object_wrap.md) + - [ClassPropertyDescriptor](doc/class_property_descriptor.md) +- [Buffer](doc/buffer.md) +- [ArrayBuffer](doc/array_buffer.md) +- [TypedArray](doc/typed_array.md) + - [TypedArrayOf](doc/typed_array_of.md) From efbacd83123a3d10085a815a68a1b233d7375a79 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Tue, 18 Sep 2018 10:56:13 -0400 Subject: [PATCH 5/9] squash: fix typo --- doc/async_worker.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/async_worker.md b/doc/async_worker.md index ad04eb04e..100470350 100644 --- a/doc/async_worker.md +++ b/doc/async_worker.md @@ -235,7 +235,7 @@ can be used to mix usage of the C N-API and node-addon-api. ## Example The first step to use the `Napi::AsyncWorker` class is to create a new class that -inherit from it and implement the `Execute` abstract method. Typically input to your +inherits from it and implement the `Execute` abstract method. Typically input to your worker will be saved within class' fields generally passed in through its constructor. From 482df541a997db7dc12873e8779c5f2eec245758 Mon Sep 17 00:00:00 2001 From: NickNaso Date: Tue, 18 Sep 2018 22:32:00 +0200 Subject: [PATCH 6/9] Added some missed changes --- doc/basic_types.md | 8 ++++---- doc/boolean.md | 2 +- doc/callbackinfo.md | 4 ++-- doc/error.md | 6 +++--- doc/escapable_handle_scope.md | 2 +- doc/function.md | 2 +- doc/object.md | 2 +- doc/object_reference.md | 6 +++--- doc/range_error.md | 4 ++-- doc/string.md | 8 ++++---- doc/symbol.md | 4 ++-- doc/typed_array_of.md | 4 ++-- doc/value.md | 11 ++++++----- 13 files changed, 32 insertions(+), 31 deletions(-) diff --git a/doc/basic_types.md b/doc/basic_types.md index 72033f1bb..7e65ead1b 100644 --- a/doc/basic_types.md +++ b/doc/basic_types.md @@ -37,7 +37,7 @@ in. #### operator napi_value ```cpp -operator napi_value() const; +Napi::Value::operator napi_value() const; ``` Returns the underlying N-API `napi_value`. If the instance is _empty_, this @@ -46,7 +46,7 @@ returns `nullptr`. #### operator == ```cpp -bool operator ==(const Value& other) const; +bool Napi::Value::operator ==(const Value& other) const; ``` Returns `true` if this value strictly equals another value, or `false` otherwise. @@ -54,7 +54,7 @@ Returns `true` if this value strictly equals another value, or `false` otherwise #### operator != ```cpp -bool operator !=(const Value& other) const; +bool Napi::Value::operator !=(const Value& other) const; ``` Returns `false` if this value strictly equals another value, or `true` otherwise. @@ -259,7 +259,7 @@ otherwise. #### ToBoolean ```cpp -Boolean Napi::Value::ToBoolean() const; +Napi::Boolean Napi::Value::ToBoolean() const; ``` Returns a `Napi::Boolean` representing the `Napi::Value`. diff --git a/doc/boolean.md b/doc/boolean.md index a6d234dbe..2886b1d0c 100644 --- a/doc/boolean.md +++ b/doc/boolean.md @@ -18,7 +18,7 @@ returns a new empty Javascript Boolean value type. ### operator bool Converts a `Napi::Boolean` value to a boolean primitive. ```cpp -operator bool() const; +Napi::Boolean::operator bool() const; ``` ### Value diff --git a/doc/callbackinfo.md b/doc/callbackinfo.md index af5d6b7d5..0bf4e1ad1 100644 --- a/doc/callbackinfo.md +++ b/doc/callbackinfo.md @@ -92,6 +92,6 @@ Returns `void`. ```cpp Napi::CallbackInfo::~CallbackInfo(); // Disallow copying to prevent multiple free of _dynamicArgs -CallbackInfo(CallbackInfo const &) = delete; -void operator=(CallbackInfo const &) = delete; +Napi::CallbackInfo::CallbackInfo(CallbackInfo const &) = delete; +void Napi::CallbackInfo::operator=(CallbackInfo const &) = delete; ``` diff --git a/doc/error.md b/doc/error.md index b6218ebcd..1526bddf0 100644 --- a/doc/error.md +++ b/doc/error.md @@ -20,7 +20,7 @@ For more details about error handling refer to the section titled [Error handlin Creates empty instance of an `Napi::Error` object for the specified environment. ```cpp -Napi::Error::New(Napi:Env env); +Napi::Error::New(Napi::Env env); ``` - `[in] env`: The environment in which to construct the `Napi::Error` object. @@ -32,7 +32,7 @@ Returns an instance of `Napi::Error` object. Creates instance of an `Napi::Error` object. ```cpp -Napi::Error::New(Napi:Env env, const char* message); +Napi::Error::New(Napi::Env env, const char* message); ``` - `[in] env`: The environment in which to construct the `Napi::Error` object. @@ -45,7 +45,7 @@ Returns instance of an `Napi::Error` object. Creates instance of an `Napi::Error` object ```cpp -Napi::Error::New(Napi:Env env, const std::string& message); +Napi::Error::New(Napi::Env env, const std::string& message); ``` - `[in] env`: The environment in which to construct the `Napi::Error` object. diff --git a/doc/escapable_handle_scope.md b/doc/escapable_handle_scope.md index 20cbd5763..978aab354 100644 --- a/doc/escapable_handle_scope.md +++ b/doc/escapable_handle_scope.md @@ -79,4 +79,4 @@ more than once an exception will be thrown. Napi::Env Napi::EscapableHandleScope::Env() const; ``` -Returns the `Napi:Env` associated with the `Napi::EscapableHandleScope`. +Returns the `Napi::Env` associated with the `Napi::EscapableHandleScope`. diff --git a/doc/function.md b/doc/function.md index 4931d6106..3e8351ba3 100644 --- a/doc/function.md +++ b/doc/function.md @@ -274,7 +274,7 @@ Returns a `Napi::Value` representing the JavaScript value returned by the functi ## Operator ```cpp -Napi::Value operator ()(const std::initializer_list& args) const; +Napi::Value Napi::Function::operator ()(const std::initializer_list& args) const; ``` - `[in] args`: Initializer list of JavaScript values as `napi_value`. diff --git a/doc/object.md b/doc/object.md index 5be58c499..3e32fa4e9 100644 --- a/doc/object.md +++ b/doc/object.md @@ -140,7 +140,7 @@ Note: This is equivalent to the JavaScript instanceof operator. ### DefineProperty() ```cpp -void Napi::Object::DefineProperty (const PropertyDescriptor& property); +void Napi::Object::DefineProperty (const Napi::PropertyDescriptor& property); ``` - `[in] property`: A [`Napi::PropertyDescriptor`](propertydescriptor.md). diff --git a/doc/object_reference.md b/doc/object_reference.md index 1773296e1..4c20f16f8 100644 --- a/doc/object_reference.md +++ b/doc/object_reference.md @@ -30,7 +30,7 @@ void Init(Env env) { ### Initialization ```cpp -static Napi::ObjectReference Napi::ObjectReference::New(const Object& value, uint32_t initialRefcount = 0); +static Napi::ObjectReference Napi::ObjectReference::New(const Napi::Object& value, uint32_t initialRefcount = 0); ``` * `[in] value`: The `Napi::Object` which is to be referenced. @@ -40,7 +40,7 @@ static Napi::ObjectReference Napi::ObjectReference::New(const Object& value, uin Returns the newly created reference. ```cpp -static Napi::ObjectReference Napi::ObjectReference::Weak(const Object& value); +static Napi::ObjectReference Napi::ObjectReference::Weak(const Napi::Object& value); ``` Creates a "weak" reference to the value, in that the initial count of number of references is set to 0. @@ -50,7 +50,7 @@ Creates a "weak" reference to the value, in that the initial count of number of Returns the newly created reference. ```cpp -static Napi::ObjectReference Napi::ObjectReference::Persistent(const Object& value); +static Napi::ObjectReference Napi::ObjectReference::Persistent(const Napi::Object& value); ``` Creates a "persistent" reference to the value, in that the initial count of number of references is set to 1. diff --git a/doc/range_error.md b/doc/range_error.md index adefb96cb..e134a4098 100644 --- a/doc/range_error.md +++ b/doc/range_error.md @@ -16,7 +16,7 @@ For more details about error handling refer to the section titled [Error handlin Creates a new instance of a `Napi::RangeError` object. ```cpp -Napi::RangeError::New(Napi:Env env, const char* message); +Napi::RangeError::New(Napi::Env env, const char* message); ``` - `[in] Env`: The environment in which to construct the `Napi::RangeError` object. @@ -29,7 +29,7 @@ Returns an instance of a `Napi::RangeError` object. Creates a new instance of a `Napi::RangeError` object. ```cpp -Napi::RangeError::New(Napi:Env env, const std::string& message); +Napi::RangeError::New(Napi::Env env, const std::string& message); ``` - `[in] Env`: The environment in which to construct the `Napi::RangeError` object. diff --git a/doc/string.md b/doc/string.md index 874d3d4db..21ce8f8cb 100644 --- a/doc/string.md +++ b/doc/string.md @@ -29,14 +29,14 @@ attempting to use the returned value. ### operator std::string ```cpp -operator std::string() const; +Napi::String::operator std::string() const; ``` Returns a UTF-8 encoded C++ string. ### operator std::u16string ```cpp -operator std::u16string() const; +Napi::String::operator std::u16string() const; ``` Returns a UTF-16 encoded C++ string. @@ -52,8 +52,8 @@ Returns a new empty `Napi::String`. ### New ```cpp -Napi::String::New(napi_env env, const std::Napi::string& value); -Napi::String::New(napi_env env, const std::u16Napi::string& value); +Napi::String::New(napi_env env, const std::string& value); +Napi::String::New(napi_env env, const std::u16::string& value); Napi::String::New(napi_env env, const char* value); Napi::String::New(napi_env env, const char16_t* value); ``` diff --git a/doc/symbol.md b/doc/symbol.md index 0fb37fb7e..13abe3e20 100644 --- a/doc/symbol.md +++ b/doc/symbol.md @@ -16,7 +16,7 @@ Returns a new empty `Napi::Symbol`. ```cpp Napi::Symbol::New(napi_env env, const std::string& description); Napi::Symbol::New(napi_env env, const char* description); -Napi::Symbol::New(napi_env env, String description); +Napi::Symbol::New(napi_env env, Napi::String description); Napi::Symbol::New(napi_env env, napi_value description); ``` @@ -29,7 +29,7 @@ Napi::Symbol::New(napi_env env, napi_value description); - `napi_value` - N-API `napi_value` description. If an error occurs, a `Napi::Error` will get thrown. If C++ exceptions are not -being used, callers should check the result of `Env::IsExceptionPending` before +being used, callers should check the result of `Napi::Env::IsExceptionPending` before attempting to use the returned value. ### Utf8Value diff --git a/doc/typed_array_of.md b/doc/typed_array_of.md index c0f1ad043..fc30218c1 100644 --- a/doc/typed_array_of.md +++ b/doc/typed_array_of.md @@ -97,7 +97,7 @@ Napi::TypedArrayOf::TypedArrayOf(napi_env env, napi_value value); ### operator [] ```cpp -T& operator [](size_t index); +T& Napi::TypedArrayOf::operator [](size_t index); ``` - `[in] index: The element index into the array. @@ -107,7 +107,7 @@ Returns the element found at the given index. ### operator [] ```cpp -const T& operator [](size_t index) const; +const T& Napi::TypedArrayOf::operator [](size_t index) const; ``` - `[in] index: The element index into the array. diff --git a/doc/value.md b/doc/value.md index efe82a4d4..e9f9f8a7f 100644 --- a/doc/value.md +++ b/doc/value.md @@ -59,7 +59,7 @@ template static Napi::Value Napi::Value::From(napi_env env, const T - `[in] value`: The N-API primitive value from which to create the `Napi::Value` object. -Returns a Value object from an N-API primitive value. +Returns a `Napi::Value` object from an N-API primitive value. ### operator napi_value @@ -74,7 +74,8 @@ Returns `nullptr` if this `Napi::Value` is *empty*. ### operator == ```cpp -bool operator ==(const Value& other) const; + +bool Napi::Value::operator ==(const Napi::Value& other) const; ``` - `[in] other`: The `Napi::Value` object to be compared. @@ -84,17 +85,17 @@ Returns a `bool` indicating if this `Napi::Value` strictly equals another `Napi: ### operator != ```cpp -bool operator !=(const Value& other) const; +bool Napi::Value::operator !=(const Napi::Value& other) const; ``` -- `[in] other`: The Value object to be compared. +- `[in] other`: The `Napi::Value` object to be compared. Returns a `bool` indicating if this `Napi::Value` does not strictly equal another `Napi::Value`. ### StrictEquals ```cpp -bool Napi::Value::StrictEquals(const Value& other) const; +bool Napi::Value::StrictEquals(const Napi::Value& other) const; ``` - `[in] other`: The `Napi::Value` object to be compared. From fd10e91cfeca951a7fd6664e7f4474edd5150677 Mon Sep 17 00:00:00 2001 From: NickNaso Date: Tue, 18 Sep 2018 22:57:40 +0200 Subject: [PATCH 7/9] Fixed problems on AsyncWorker documentation --- doc/async_worker.md | 120 +++++++++++++++++++++++++------------------- 1 file changed, 67 insertions(+), 53 deletions(-) diff --git a/doc/async_worker.md b/doc/async_worker.md index 100470350..db0e143f9 100644 --- a/doc/async_worker.md +++ b/doc/async_worker.md @@ -1,17 +1,19 @@ # AsyncWorker -`Napi::AsyncWorker` is an abstract class that you can subclass to remove many of the -tedious tasks of moving data between the event loop and worker threads. This +`Napi::AsyncWorker` is an abstract class that you can subclass to remove many of +the tedious tasks of moving data between the event loop and worker threads. This class internally handles all the details of creating and executing an asynchronous operation. -Once created, execution is requested by calling `Queue`. When a thread is -available for execution the `Execute` method will be invoked. Once `Execute` -complets either `OnOK` or `OnError` will be invoked. Once the `OnOK` or -`OnError` methods are complete the `Napi::AsyncWorker` instance is destructed. +Once created, execution is requested by calling `Napi::AsyncWorker::Queue`. When +a thread is available for execution the `Napi::AsyncWorker::Execute` method will +be invoked. Once `Napi::AsyncWorker::Execute` complets either +`Napi::AsyncWorker::OnOK` or `Napi::AsyncWorker::OnError` will be invoked. Once +the `Napi::AsyncWorker::OnOK` or `Napi::AsyncWorker::OnError` methods are +complete the `Napi::AsyncWorker` instance is destructed. -For the most basic use, only the `Execute` method must be implemented in a -subclass. +For the most basic use, only the `Napi::AsyncWorker::Execute` method must be +implemented in a subclass. ## Methods @@ -60,14 +62,16 @@ Napi::FunctionReference& Napi::AsyncWorker::Callback(); Returns the persistent function reference of the callback set when the async worker was created. The returned function reference will receive the results of -the computation that happened in the `Execute` method, unless the default -implementation of `OnOK` or `OnError` is overridden. +the computation that happened in the `Napi::AsyncWorker::Execute` method, unless +the default implementation of `Napi::AsyncWorker::OnOK` or +`Napi::AsyncWorker::OnError` is overridden. ### SetError Sets the error message for the error that happened during the execution. Setting -an error message will cause the `OnError` method to be invoked instead of `OnOK` -once the `Execute` method completes. +an error message will cause the `Napi::AsyncWorker::OnError` method to be +invoked instead of `OnOK` once the `Napi::AsyncWorker::OnError::Execute` method +completes. ```cpp void Napi::AsyncWorker::SetError(const std::string& error); @@ -81,10 +85,10 @@ This method is used to execute some tasks out of the **event loop** on a libuv worker thread. Subclasses must implement this method and the method is run on a thread other than that running the main event loop. As the method is not running on the main event loop, it must avoid calling any methods from node-addon-api -or running any code that might invoke JavaScript. Instead once this method is +or running any code that might invoke JavaScript. Instead, once this method is complete any interaction through node-addon-api with JavaScript should be implemented -in the `OnOK` method which runs on the main thread and is invoked when the `Execute` -method completes. +in the `Napi::AsyncWorker::OnOK` method which runs on the main thread and is +invoked when the `Napi::AsyncWorker::Execute` method completes. ```cpp virtual void Napi::AsyncWorker::Execute() = 0; @@ -102,14 +106,14 @@ virtual void Napi::AsyncWorker::OnOK(); ### OnError -This method is invoked afer Execute() completes if an error occurs -while `Execute` is running and C++ exceptions are enabled or if an -error was set through a call to `SetError`. The default implementation -calls the callback provided when the AsyncWorker class was created, passing -in the error as the first parameter. +This method is invoked afer `Napi::AsyncWorker::Execute` completes if an error +occurs while `Napi::AsyncWorker::Execute` is running and C++ exceptions are +enabled or if an error was set through a call to `Napi::AsyncWorker::SetError`. +The default implementation calls the callback provided when the `Napi::AsyncWorker` +class was created, passing in the error as the first parameter. ```cpp -virtual void Napi::AsyncWorker::OnError(const Error& e); +virtual void Napi::AsyncWorker::OnError(const Napi::Error& e); ``` ### Constructor @@ -117,7 +121,7 @@ virtual void Napi::AsyncWorker::OnError(const Error& e); Creates a new `Napi::AsyncWorker`. ```cpp -explicit Napi::AsyncWorker(const Function& callback); +explicit Napi::AsyncWorker(const Napi::Function& callback); ``` - `[in] callback`: The function which will be called when an asynchronous @@ -131,7 +135,7 @@ Returns a`Napi::AsyncWork` instance which can later be queued for execution by c Creates a new `Napi::AsyncWorker`. ```cpp -explicit Napi::AsyncWorker(const Function& callback, const char* resource_name); +explicit Napi::AsyncWorker(const Napi::Function& callback, const char* resource_name); ``` - `[in] callback`: The function which will be called when an asynchronous @@ -140,15 +144,15 @@ operations ends. The given function is called from the main event loop thread. identifier for the kind of resource that is being provided for diagnostic information exposed by the async_hooks API. -Returns a `Napi::AsyncWork` instance which can later be queued for execution by calling -`Queue`. +Returns a `Napi::AsyncWork` instance which can later be queued for execution by +calling `Napi::AsyncWork::Queue`. ### Constructor Creates a new `Napi::AsyncWorker`. ```cpp -explicit Napi::AsyncWorker(const Function& callback, const char* resource_name, const Object& resource); +explicit Napi::AsyncWorker(const Napi::Function& callback, const char* resource_name, const Napi::Object& resource); ``` - `[in] callback`: The function which will be called when an asynchronous @@ -159,30 +163,30 @@ information exposed by the async_hooks API. - `[in] resource`: Object associated with the asynchronous operation that will be passed to possible async_hooks. -Returns a `Napi::AsyncWork` instance which can later be queued for execution by calling -`Queue`. +Returns a `Napi::AsyncWork` instance which can later be queued for execution by +calling `Napi::AsyncWork::Queue`. ### Constructor Creates a new `Napi::AsyncWorker`. ```cpp -explicit Napi::AsyncWorker(const Object& receiver, const Function& callback); +explicit Napi::AsyncWorker(const Napi::Object& receiver, const Napi::Function& callback); ``` - `[in] receiver`: The `this` object passed to the called function. - `[in] callback`: The function which will be called when an asynchronous operations ends. The given function is called from the main event loop thread. -Returns a `Napi::AsyncWork` instance which can later be queued for execution by calling -`Queue`. +Returns a `Napi::AsyncWork` instance which can later be queued for execution by +calling `Napi::AsyncWork::Queue`. ### Constructor Creates a new `Napi::AsyncWorker`. ```cpp -explicit Napi::AsyncWorker(const Object& receiver, const Function& callback,const char* resource_name); +explicit Napi::AsyncWorker(const Napi::Object& receiver, const Napi::Function& callback,const char* resource_name); ``` - `[in] receiver`: The `this` object passed to the called function. @@ -192,15 +196,15 @@ operations ends. The given function is called from the main event loop thread. identifier for the kind of resource that is being provided for diagnostic information exposed by the async_hooks API. -Returns a `Napi::AsyncWork` instance which can later be queued for execution by calling -`Queue`. +Returns a `Napi::AsyncWork` instance which can later be queued for execution by +calling `Napi::AsyncWork::Queue`. ### Constructor Creates a new `Napi::AsyncWorker`. ```cpp -explicit Napi::AsyncWorker(const Object& receiver, const Function& callback, const char* resource_name, const Object& resource); +explicit Napi::AsyncWorker(const Napi::Object& receiver, const Napi::Function& callback, const char* resource_name, const Napi::Object& resource); ``` - `[in] receiver`: The `this` object passed to the called function. @@ -212,21 +216,21 @@ information exposed by the async_hooks API. - `[in] resource`: Object associated with the asynchronous operation that will be passed to possible async_hooks. -Returns a `Napi::AsyncWork` instance which can later be queued for execution by calling -`Queue`. +Returns a `Napi::AsyncWork` instance which can later be queued for execution by +calling `Napi::AsyncWork::Queue`. ### Destructor Deletes the created work object that is used to execute logic asynchronously. ```cpp -virtual Napi::~AsyncWorker(); +virtual Napi::AsyncWorker::~AsyncWorker(); ``` ## Operator ```cpp -operator napi_async_work() const; +Napi::AsyncWorker::operator napi_async_work() const; ``` Returns the N-API napi_async_work wrapped by the `Napi::AsyncWorker` object. This @@ -235,17 +239,19 @@ can be used to mix usage of the C N-API and node-addon-api. ## Example The first step to use the `Napi::AsyncWorker` class is to create a new class that -inherits from it and implement the `Execute` abstract method. Typically input to your -worker will be saved within class' fields generally passed in through its -constructor. +inherits from it and implement the `Napi::AsyncWorker::Execute` abstract method. +Typically input to your worker will be saved within class' fields generally +passed in through its constructor. -When the `Execute` method completes without errors the `OnOK` function callback -will be invoked. In this function the results of the computation will be -reassembled and returned back to the initial JavaScript context. +When the `Napi::AsyncWorker::Execute` method completes without errors the +`Napi::AsyncWorker::OnOK` function callback will be invoked. In this function the +results of the computation will be reassembled and returned back to the initial +JavaScript context. -`Napi::AsyncWorker` ensures that all the code in the `Execute` function runs in the -background out of the **event loop** thread and at the end the `OnOK` or `OnError` -function will be called and are executed as part of the event loop. +`Napi::AsyncWorker` ensures that all the code in the `Napi::AsyncWorker::Execute` +function runs in the background out of the **event loop** thread and at the end +the `Napi::AsyncWorker::OnOK` or `Napi::AsyncWorker::OnError` function will be +called and are executed as part of the event loop. The code below show a basic example of `Napi::AsyncWorker` the implementation: @@ -288,6 +294,13 @@ associated environment. The following code shows an example on how to create and and use an `Napi::AsyncWorker` ```cpp +#include + +// Include EchoWorker class +// .. + +use namespace Napi; + Value Echo(const CallbackInfo& info) { // You need to check the input data here Function cb = info[1].As(); @@ -297,8 +310,9 @@ Value Echo(const CallbackInfo& info) { return info.Env().Undefined(); ``` -Using the implementation of a `Napi::AsyncWorker` is straight forward. You need only create -a new instance and pass to its constructor the callback you want to execute when -your asynchronous task ends and other data you need for your computation. Once created the -only other action you have to do is to call the `Queue` method that will that will -queue the created worker for execution. +Using the implementation of a `Napi::AsyncWorker` is straight forward. You need +only create a new instance and pass to its constructor the callback you want to +execute when your asynchronous task ends and other data you need for your +computation. Once created the only other action you have to do is to call the +`Napi::AsyncWorker::Queue` method that will that will queue the created worker +for execution. From 57690089080dbda552139d5c798aa32a9377a7db Mon Sep 17 00:00:00 2001 From: NickNaso Date: Wed, 19 Sep 2018 13:33:05 +0200 Subject: [PATCH 8/9] Some fix after review by @thefourtheye --- doc/async_worker.md | 19 +++++++++---------- doc/handle_scope.md | 4 ++-- doc/promises.md | 2 +- doc/property_descriptor.md | 2 +- 4 files changed, 13 insertions(+), 14 deletions(-) diff --git a/doc/async_worker.md b/doc/async_worker.md index db0e143f9..7fd533ee7 100644 --- a/doc/async_worker.md +++ b/doc/async_worker.md @@ -7,7 +7,7 @@ operation. Once created, execution is requested by calling `Napi::AsyncWorker::Queue`. When a thread is available for execution the `Napi::AsyncWorker::Execute` method will -be invoked. Once `Napi::AsyncWorker::Execute` complets either +be invoked. Once `Napi::AsyncWorker::Execute` completes either `Napi::AsyncWorker::OnOK` or `Napi::AsyncWorker::OnError` will be invoked. Once the `Napi::AsyncWorker::OnOK` or `Napi::AsyncWorker::OnError` methods are complete the `Napi::AsyncWorker` instance is destructed. @@ -70,8 +70,8 @@ the default implementation of `Napi::AsyncWorker::OnOK` or Sets the error message for the error that happened during the execution. Setting an error message will cause the `Napi::AsyncWorker::OnError` method to be -invoked instead of `OnOK` once the `Napi::AsyncWorker::OnError::Execute` method -completes. +invoked instead of `Napi::AsyncWorker::OnOKOnOK` once the +`Napi::AsyncWorker::Execute` method completes. ```cpp void Napi::AsyncWorker::SetError(const std::string& error); @@ -287,9 +287,9 @@ class EchoWorker : public AsyncWorker { The `EchoWorker`'s contructor calls the base class' constructor to pass in the callback that the `Napi::AsyncWorker` base class will store persistently. When -the work on the `Execute` method is done the `OnOk` method is called and the -results return back to JavaScript invoking the stored callback with its -associated environment. +the work on the `Napi::AsyncWorker::Execute` method is done the +`Napi::AsyncWorker::OnOk` method is called and the results return back to +JavaScript invoking the stored callback with its associated environment. The following code shows an example on how to create and and use an `Napi::AsyncWorker` @@ -310,9 +310,8 @@ Value Echo(const CallbackInfo& info) { return info.Env().Undefined(); ``` -Using the implementation of a `Napi::AsyncWorker` is straight forward. You need -only create a new instance and pass to its constructor the callback you want to +Using the implementation of a `Napi::AsyncWorker` is straight forward. You only +need to create a new instance and pass to its constructor the callback you want to execute when your asynchronous task ends and other data you need for your computation. Once created the only other action you have to do is to call the -`Napi::AsyncWorker::Queue` method that will that will queue the created worker -for execution. +`Napi::AsyncWorker::Queue` method that will queue the created worker for execution. diff --git a/doc/handle_scope.md b/doc/handle_scope.md index f06f87bc8..9b34fcf2f 100644 --- a/doc/handle_scope.md +++ b/doc/handle_scope.md @@ -15,7 +15,7 @@ the section titled [Object lifetime management](object_lifetime_management.md). Creates a new handle scope on the stack. ```cpp -Napi::HandleScope::HandleScope(Napi:Env env); +Napi::HandleScope::HandleScope(Napi::Env env); ``` - `[in] env`: The environment in which to construct the `Napi::HandleScope` object. @@ -62,4 +62,4 @@ guarantee as to when the gargbage collector will do this. Napi::Env Napi::HandleScope::Env() const; ``` -Returns the `Napi:Env` associated with the `Napi::HandleScope`. +Returns the `Napi::Env` associated with the `Napi::HandleScope`. diff --git a/doc/promises.md b/doc/promises.md index bd23a51d5..62529006b 100644 --- a/doc/promises.md +++ b/doc/promises.md @@ -1,6 +1,6 @@ # Promise -The `Napi::Promise` class, along with its `Napi::Promise::Deferred` class, implement the ability to create, resolve, and reject `Promise` objects. +The `Napi::Promise` class, along with its `Napi::Promise::Deferred` class, implement the ability to create, resolve, and reject Promise objects. The basic approach is to create a `Napi::Promise::Deferred` object and return to your caller the value returned by the `Napi::Promise::Deferred::Promise` method. For example: diff --git a/doc/property_descriptor.md b/doc/property_descriptor.md index 0f7dc8eee..2c0fa6fac 100644 --- a/doc/property_descriptor.md +++ b/doc/property_descriptor.md @@ -1,6 +1,6 @@ # Property Descriptor -A [`Napi::Object`](object.md) can be assigned properites via its [`DefineProperty`](object.md#defineproperty) and [`DefineProperties`](object.md#defineproperties) function, which take PropertyDescrptor(s) as their parameters. The `Napi::PropertyDescriptor` can contain either values or functions, which are then assigned to the `Napi::Object`. Note that a single instance of a `Napi::PropertyDescriptor` class can only contain either one value, or at most two functions. PropertyDescriptors can only be created through the class methods [`Accessor`](#accessor), [`Function`](#function), or [`Value`](#value), each of which return a new static instance of a `Napi::PropertyDescriptor`. +A [`Napi::Object`](object.md) can be assigned properites via its [`DefineProperty`](object.md#defineproperty) and [`DefineProperties`](object.md#defineproperties) functions, which take PropertyDescrptor(s) as their parameters. The `Napi::PropertyDescriptor` can contain either values or functions, which are then assigned to the `Napi::Object`. Note that a single instance of a `Napi::PropertyDescriptor` class can only contain either one value, or at most two functions. PropertyDescriptors can only be created through the class methods [`Accessor`](#accessor), [`Function`](#function), or [`Value`](#value), each of which return a new static instance of a `Napi::PropertyDescriptor`. ## Example From eaf1e91393b2f49b0be25b60d8a0fa85c289b0fa Mon Sep 17 00:00:00 2001 From: NickNaso Date: Wed, 19 Sep 2018 15:15:21 +0200 Subject: [PATCH 9/9] Fixed typo in JavaScript word --- doc/function_reference.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/function_reference.md b/doc/function_reference.md index 44998d7ae..70c6d061d 100644 --- a/doc/function_reference.md +++ b/doc/function_reference.md @@ -106,7 +106,7 @@ function. ### Call -Calls a referenced Javascript function from a native add-on. +Calls a referenced JavaScript function from a native add-on. ```cpp Napi::Value Napi::FunctionReference::Call(const std::vector& args) const; @@ -120,7 +120,7 @@ function. ### Call -Calls a referenced Javascript function from a native add-on. +Calls a referenced JavaScript function from a native add-on. ```cpp Napi::Value Napi::FunctionReference::Call(napi_value recv, const std::initializer_list& args) const; @@ -135,7 +135,7 @@ function. ### Call -Calls a referenced Javascript function from a native add-on. +Calls a referenced JavaScript function from a native add-on. ```cpp Napi::Value Napi::FunctionReference::Call(napi_value recv, const std::vector& args) const; @@ -150,7 +150,7 @@ function. ### MakeCallback -Calls a referenced Javascript function from a native add-on after an asynchronous +Calls a referenced JavaScript function from a native add-on after an asynchronous operation. ```cpp @@ -166,7 +166,7 @@ function. ### MakeCallback -Calls a referenced Javascript function from a native add-on after an asynchronous +Calls a referenced JavaScript function from a native add-on after an asynchronous operation. ```cpp