From 17b299db03c6ef6b06b030d49d66f18a1adfc43c Mon Sep 17 00:00:00 2001 From: NickNaso Date: Tue, 19 Jun 2018 01:44:11 +0200 Subject: [PATCH 01/13] Initial commit for function and function reference documentation --- doc/function.md | 195 +++++++++++++++++++++++++++++++++++++- doc/function_reference.md | 136 +++++++++++++++++++++++++- 2 files changed, 324 insertions(+), 7 deletions(-) diff --git a/doc/function.md b/doc/function.md index e4d7c92fc..50ddb6752 100644 --- a/doc/function.md +++ b/doc/function.md @@ -1,5 +1,194 @@ # Function -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/) +N-API provides a set of APIs that allow JavaScript code to call back into native code. N-API APIs that support calling back into native code take in a callback functions represented by the napi_callback type. When the JavaScript VM calls back to native code, the napi_callback function provided is invoked. The APIs documented in this section allow the callback function to do the following: + +This API returns an N-API value corresponding to a JavaScript Function object. It's used to wrap native functions so that they can be invoked from JavaScript. + +JavaScript Functions are described in Section 19.2 of the ECMAScript Language Specification. + +In JavaScript, functions are first-class objects, because they can have properties and methods just like any other object. What distinguishes them from other objects is that functions can be called. In brief, they are Function objects. + +Node Addon API consists of a few fundamental data types. These allow a user of the API to create, convert and introspect fundamental JavaScript types, and interop with their C++ counterparts. + +Value +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 napi_value and also convert to C++ types. + +## Methods + +### Constructor + +Creates a new + +```cpp +Function(); +``` + +- `[in] Env`: The environment in which to construct the + +Returns a new + +### Constructor + +Creates a new + +```cpp +Function(napi_env env, napi_value value); +``` + +- `[in] Env`: The environment in which to construct the + +Returns a new + +### Call + +Creates a new + +```cpp +Value Call(const std::initializer_list& args) const; +``` + +- `[in] Env`: The environment in which to construct the + +Returns a new + +### Call + +Creates a new + +```cpp +Value Call(const std::vector& args) const; +``` + +- `[in] Env`: The environment in which to construct the + +Returns a new + +### Call + +Creates a new + +```cpp +Value Call(size_t argc, const napi_value* args) const; +``` + +- `[in] Env`: The environment in which to construct the + +Returns a new + +### Call + +Creates a new + +```cpp +Value Call(napi_value recv, const std::initializer_list& args) const; +``` + +- `[in] Env`: The environment in which to construct the + +Returns a new + +### Call + +Creates a new + +```cpp +Value Call(napi_value recv, const std::vector& args) const; +``` + +- `[in] Env`: The environment in which to construct the + +Returns a new + +### Call + +Creates a new + +```cpp +Value Call(napi_value recv, size_t argc, const napi_value* args) const; +``` + +- `[in] Env`: The environment in which to construct the + +Returns a new + +### MakeCallback + +Creates a new + +```cpp +Value MakeCallback(napi_value recv, const std::initializer_list& args) const; +``` + +- `[in] Env`: The environment in which to construct the + +Returns a new + +### MakeCallback + +Creates a new + +```cpp +Value MakeCallback(napi_value recv, const std::vector& args) const; +``` + +- `[in] Env`: The environment in which to construct the + +Returns a new + +### MakeCallback + +Creates a new + +```cpp +Value MakeCallback(napi_value recv, const std::vector& args) const; +``` + +- `[in] Env`: The environment in which to construct the + +Returns a new + +### New + +Creates a new + +```cpp +Object New(const std::initializer_list& args) const; +``` + +- `[in] Env`: The environment in which to construct the + +Returns a new + +### New + +Creates a new + +```cpp +Object New(const std::vector& args) const; +``` + +- `[in] Env`: The environment in which to construct the + +Returns a new + +### New + +Creates a new + +```cpp +Object New(size_t argc, const napi_value* args) const; +``` + +- `[in] Env`: The environment in which to construct the + +Returns a new + +## Operator + +```cpp +Value operator ()(const std::initializer_list& args) const; +``` + +- `[in] Env`: The environment in which to construct the + +Returns a new diff --git a/doc/function_reference.md b/doc/function_reference.md index 1978b81b4..6c9fe80fe 100644 --- a/doc/function_reference.md +++ b/doc/function_reference.md @@ -1,5 +1,133 @@ -# Function reference +# FunctionReference -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 + +Creates a new + +```cpp +FunctionReference(); +``` + +- `[in] Env`: The environment in which to construct the + +Returns a new + +### Constructor + +Creates a new + +```cpp +FunctionReference(napi_env env, napi_ref ref); +``` + +- `[in] Env`: The environment in which to construct the + +Returns a new + +### Call + +Creates a new + +```cpp +Napi::Value Call(const std::initializer_list& args) const; +``` + +- `[in] Env`: The environment in which to construct the + +Returns a new + +### Call + +Creates a new + +```cpp +Napi::Value Call(const std::vector& args) const; +``` + +- `[in] Env`: The environment in which to construct the + +Returns a new + +### Call + +Creates a new + +```cpp +Napi::Value Call(napi_value recv, const std::initializer_list& args) const; +``` + +- `[in] Env`: The environment in which to construct the + +Returns a new + +### Call + +Creates a new + +```cpp +Napi::Value Call(napi_value recv, const std::vector& args) const; +``` + +- `[in] Env`: The environment in which to construct the + +Returns a new + +### MakeCallback + +Creates a new + +```cpp +Napi::Value MakeCallback(napi_value recv, const std::initializer_list& args) const; +``` + +- `[in] Env`: The environment in which to construct the + +Returns a new + +### MakeCallback + +Creates a new + +```cpp +Napi::Value MakeCallback(napi_value recv, const std::vector& args) const; +``` + +- `[in] Env`: The environment in which to construct the + +Returns a new + +### New + +Creates a new + +```cpp +Object New(const std::initializer_list& args) const; +``` + +- `[in] Env`: The environment in which to construct the + +Returns a new + +### New + +Creates a new + +```cpp +Object New(const std::vector& args) const; +``` + +- `[in] Env`: The environment in which to construct the + +Returns a new + +## Operator + +```cpp +Napi::Value operator ()(const std::initializer_list& args) const; +``` + +- `[in] Env`: The environment in which to construct the + +Returns a new From d2293c571cc23492e088aff70da9c5b146f91e3d Mon Sep 17 00:00:00 2001 From: NickNaso Date: Thu, 12 Jul 2018 11:36:38 +0200 Subject: [PATCH 02/13] First pass on function documentation --- doc/function.md | 175 ++++++++++++++++++++++++++++++++---------------- 1 file changed, 118 insertions(+), 57 deletions(-) diff --git a/doc/function.md b/doc/function.md index 50ddb6752..be1f7a431 100644 --- a/doc/function.md +++ b/doc/function.md @@ -1,187 +1,248 @@ # Function -N-API provides a set of APIs that allow JavaScript code to call back into native code. N-API APIs that support calling back into native code take in a callback functions represented by the napi_callback type. When the JavaScript VM calls back to native code, the napi_callback function provided is invoked. The APIs documented in this section allow the callback function to do the following: +The **Function** class is a representation of the JavaScript function. A function +is a JavaScript procedure, a set of statements that performs a task or calculates +a value. This class provides some methods to create and exectue a function. -This API returns an N-API value corresponding to a JavaScript Function object. It's used to wrap native functions so that they can be invoked from JavaScript. +The `Function` class inherits its behavior from the `Object` class (for more info +see: [Object](object.md)). -JavaScript Functions are described in Section 19.2 of the ECMAScript Language Specification. - -In JavaScript, functions are first-class objects, because they can have properties and methods just like any other object. What distinguishes them from other objects is that functions can be called. In brief, they are Function objects. +## Methods -Node Addon API consists of a few fundamental data types. These allow a user of the API to create, convert and introspect fundamental JavaScript types, and interop with their C++ counterparts. +### Constructor -Value -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 napi_value and also convert to C++ types. +Creates a new empty instance of `Function`. -## Methods +```cpp +Function(); +``` ### Constructor -Creates a new +Creates a new instance of `Function` object. ```cpp -Function(); +Function(napi_env env, napi_value value); ``` -- `[in] Env`: The environment in which to construct the +- `[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: -Returns a new + - 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 -### Constructor +Returns a non-empty `Function` instance. -Creates a new +### New + +Creates instance of a `Function` object. ```cpp -Function(napi_env env, napi_value value); +template +static 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 Function object. +- `[in] cb`: Object that implement the operator **()** accepting a `const CallbackInfo&` +and returns either void or Value. +- `[in] utf8name`: Null-terminated string to be used as the name of the function. +- `[in] data`: User-provided data context. This will be passed back into the +function when invoked later. + +Returns instance of a `Function` object. + +### New + +```cpp +template +static Function New(napi_env env, Callable cb, const std::string& utf8name, void* data = nullptr); ``` -- `[in] Env`: The environment in which to construct the +- `[in] env`: The `napi_env` environment in which to construct the Function object. +- `[in] cb`: Object that implement the operator **()** accepting a `const CallbackInfo&` +and returns either void or Value. +- `[in] utf8name`: String to be used as the name of the function. +- `[in] data`: User-provided data context. This will be passed back into the +function when invoked later. -Returns a new +Returns instance of a `Function` object. ### Call -Creates a new +Calls a Javascript function from a native add-on. ```cpp Value Call(const std::initializer_list& args) const; ``` -- `[in] Env`: The environment in which to construct the +- `[in] args`: Initializer list of JavaScript values as `napi_value` representing +the arguments of the function. -Returns a new +Returns a Value representing the JavaScript object returned by the function. ### Call -Creates a new +Calls a Javascript function from a native add-on. ```cpp Value Call(const std::vector& args) const; ``` -- `[in] Env`: The environment in which to construct the +- `[in] args`: List of JavaScript values as `napi_value` representing the +arguments of the function. -Returns a new +Returns a Value representing the JavaScript object returned by the function. ### Call -Creates a new +Calls a Javascript function from a native add-on. ```cpp Value Call(size_t argc, const napi_value* args) const; ``` -- `[in] Env`: The environment in which to construct the +- `[in] argc`: The number of the arguments passed to the function. +- `[in] args`: Array of JavaScript values as `napi_value` representing the +arguments of the function. -Returns a new +Returns a Value representing the JavaScript object returned by the function. ### Call -Creates a new +Calls a Javascript function from a native add-on. ```cpp Value Call(napi_value recv, const std::initializer_list& args) const; ``` -- `[in] Env`: The environment in which to construct the +- `[in] recv`: The `this` object passed to the called function. +- `[in] args`: Initializer list of JavaScript values as `napi_value` representing +the arguments of the function. -Returns a new +Returns a Value representing the JavaScript object returned by the function. ### Call -Creates a new +Calls a Javascript function from a native add-on. ```cpp Value Call(napi_value recv, const std::vector& args) const; ``` -- `[in] Env`: The environment in which to construct the +- `[in] recv`: The `this` object passed to the called function. +- `[in] args`: List of JavaScript values as `napi_value` representing the +arguments of the function. -Returns a new +Returns a Value representing the JavaScript object returned by the function. ### Call -Creates a new +Calls a Javascript function from a native add-on. ```cpp Value Call(napi_value recv, size_t argc, const napi_value* args) const; ``` -- `[in] Env`: The environment in which to construct the +- `[in] recv`: The `this` object passed to the called function. +- `[in] argc`: The number of the arguments passed to the function. +- `[in] args`: Array of JavaScript values as `napi_value` representing the +arguments of the function. -Returns a new +Returns a Value representing the JavaScript object returned by the function. ### MakeCallback -Creates a new +Calls a Javascript function from a native add-on after an asynchronous operation. ```cpp Value MakeCallback(napi_value recv, const std::initializer_list& args) const; ``` -- `[in] Env`: The environment in which to construct the +- `[in] recv`: The `this` object passed to the called function. +- `[in] args`: Initializer list of JavaScript values as `napi_value` representing +the arguments of the function. -Returns a new +Returns a Value representing the JavaScript object returned by the function. ### MakeCallback -Creates a new +Calls a Javascript function from a native add-on after an asynchronous operation. ```cpp Value MakeCallback(napi_value recv, const std::vector& args) const; ``` -- `[in] Env`: The environment in which to construct the +- `[in] recv`: The `this` object passed to the called function. +- `[in] args`: List of JavaScript values as `napi_value` representing the +arguments of the function. -Returns a new +Returns a Value representing the JavaScript object returned by the function. ### MakeCallback -Creates a new +Calls a Javascript function from a native add-on after an asynchronous operation. ```cpp -Value MakeCallback(napi_value recv, const std::vector& args) const; +Value MakeCallback(napi_value recv, size_t argc, const napi_value* args) const; ``` -- `[in] Env`: The environment in which to construct the +- `[in] recv`: The `this` object passed to the called function. +- `[in] argc`: The number of the arguments passed to the function. +- `[in] args`: Array of JavaScript values as `napi_value` representing the +arguments of the function. -Returns a new +Returns a Value representing the JavaScript object returned by the function. ### New -Creates a new +Creates a new JavaScript value from one that represents the constructor for the +object. ```cpp Object New(const std::initializer_list& args) const; ``` -- `[in] Env`: The environment in which to construct the +- `[in] args`: Initializer list of JavaScript values as `napi_value` representing +the arguments of the contructor function. -Returns a new +Returns a new JavaScript object. ### New -Creates a new +Creates a new JavaScript value from one that represents the constructor for the +object. ```cpp Object New(const std::vector& args) const; ``` -- `[in] Env`: The environment in which to construct the +- `[in] args`: List of JavaScript values as `napi_value` representing the +arguments of the constructor function. -Returns a new +Returns a new JavaScript object. ### New -Creates a new +Creates a new JavaScript value from one that represents the constructor for the +object. ```cpp Object New(size_t argc, const napi_value* args) const; ``` -- `[in] Env`: The environment in which to construct the +- `[in] argc`: The number of the arguments passed to the contructor function. +- `[in] args`: Array of JavaScript values as `napi_value` representing the +arguments of the constructor function. -Returns a new +Returns a new JavaScript object. ## Operator @@ -189,6 +250,6 @@ Returns a new Value operator ()(const std::initializer_list& args) const; ``` -- `[in] Env`: The environment in which to construct the +- `[in] args`: Initializer list of JavaScript values as `napi_value`. -Returns a new +Returns a Value representing the JavaScript object returned by the function. From 4a81a7d3181176424a4e1a80e43781b69751bbfe Mon Sep 17 00:00:00 2001 From: NickNaso Date: Thu, 2 Aug 2018 18:25:31 +0200 Subject: [PATCH 03/13] Fixed documentation for function as requested after first review --- doc/function.md | 178 +++++++++++++++++++++++++++--------------------- 1 file changed, 101 insertions(+), 77 deletions(-) diff --git a/doc/function.md b/doc/function.md index be1f7a431..7ab1e0711 100644 --- a/doc/function.md +++ b/doc/function.md @@ -1,12 +1,49 @@ # Function -The **Function** class is a representation of the JavaScript function. A function -is a JavaScript procedure, a set of statements that performs a task or calculates -a value. This class provides some methods to create and exectue a function. +The **Function** class provides a set of methods to create a function object in +native code and consequently calling it back from JavaScript. +The created function is not automatically visible from script, instead it needs to +be part of the add-on's module exports. The `Function` class inherits its behavior from the `Object` class (for more info see: [Object](object.md)). +## Example + +```cpp +#include + +using namespace Napi; + +Value Fn(const CallbackInfo& info) { + Env env = info.Env(); + // ... + return String::New(env, "Hello World"); +} + +Object Init(Env env, Object exports) { + exports.Set(String::New(env, "fn"), Function::New(env, Fn)); +} + +NODE_API_MODULE(NODE_GYP_MODULE_NAME, Init) +``` + +The above code can be used from JavaScript as follows: + +```js +const addon = require('./addon'); +addon.fn(); +``` + +The `Function` class allows to call a JavaScript function object from a native +add-on with two different methods: `Call` and `MackeCallback`. +The API of these two methods are very similar, but they are used in different context. +`MakeCallback` method is used to call from native code back into JavaScript after +returning from an [asynchronous operation](async_operations.md) and in general in +all sistuations which don't have an existing JavaScript function on the stack. +`Call` method is used when there is already a JavaScript function on the stack +(for example when running a natice method called from JavaScript). + ## Methods ### Constructor @@ -19,31 +56,20 @@ Function(); ### Constructor -Creates a new instance of `Function` object. +Creates a new instance of the `Function` object. ```cpp Function(napi_env env, napi_value 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: - - - 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 +- `[in] value`: The `napi_value` which is handle for a JavaScript function. Returns a non-empty `Function` instance. ### New -Creates instance of a `Function` object. +Creates an instance of a `Function` object. ```cpp template @@ -51,13 +77,12 @@ static Function New(napi_env env, Callable cb, const char* utf8name = nullptr, v ``` - `[in] env`: The `napi_env` environment in which to construct the Function object. -- `[in] cb`: Object that implement the operator **()** accepting a `const CallbackInfo&` -and returns either void or Value. +- `[in] cb`: Object that implements `Callable`. - `[in] utf8name`: Null-terminated string to be used as the name of the function. - `[in] data`: User-provided data context. This will be passed back into the function when invoked later. -Returns instance of a `Function` object. +Returns an instance of a `Function` object. ### New @@ -67,13 +92,55 @@ static Function New(napi_env env, Callable cb, const std::string& utf8name, void ``` - `[in] env`: The `napi_env` environment in which to construct the Function object. -- `[in] cb`: Object that implement the operator **()** accepting a `const CallbackInfo&` -and returns either void or Value. +- `[in] cb`: Object that implements `Callable`. - `[in] utf8name`: String to be used as the name of the function. - `[in] data`: User-provided data context. This will be passed back into the function when invoked later. -Returns instance of a `Function` object. +Returns an instance of a `Function` object. + +### New + +Creates a new JavaScript value from one that represents the constructor for the +object. + +```cpp +Object New(const std::initializer_list& args) const; +``` + +- `[in] args`: Initializer list of JavaScript values as `napi_value` representing +the arguments of the contructor function. + +Returns a new JavaScript object. + +### New + +Creates a new JavaScript value from one that represents the constructor for the +object. + +```cpp +Object New(const std::vector& args) const; +``` + +- `[in] args`: Vector of JavaScript values as `napi_value` representing the +arguments of the constructor function. + +Returns a new JavaScript object. + +### New + +Creates a new JavaScript value from one that represents the constructor for the +object. + +```cpp +Object New(size_t argc, const napi_value* args) const; +``` + +- `[in] argc`: The number of the arguments passed to the contructor function. +- `[in] args`: Array of JavaScript values as `napi_value` representing the +arguments of the constructor function. + +Returns a new JavaScript object. ### Call @@ -96,10 +163,10 @@ Calls a Javascript function from a native add-on. Value Call(const std::vector& args) const; ``` -- `[in] args`: List of JavaScript values as `napi_value` representing the +- `[in] args`: Vector of JavaScript values as `napi_value` representing the arguments of the function. -Returns a Value representing the JavaScript object returned by the function. +Returns a `Value` representing the JavaScript value returned by the function. ### Call @@ -113,7 +180,7 @@ Value Call(size_t argc, const napi_value* args) const; - `[in] args`: Array of JavaScript values as `napi_value` representing the arguments of the function. -Returns a Value representing the JavaScript object returned by the function. +Returns a `Value` representing the JavaScript value returned by the function. ### Call @@ -127,7 +194,7 @@ Value Call(napi_value recv, const std::initializer_list& args) const - `[in] args`: Initializer list of JavaScript values as `napi_value` representing the arguments of the function. -Returns a Value representing the JavaScript object returned by the function. +Returns a `Value` representing the JavaScript value returned by the function. ### Call @@ -138,10 +205,10 @@ Value Call(napi_value recv, const std::vector& args) const; ``` - `[in] recv`: The `this` object passed to the called function. -- `[in] args`: List of JavaScript values as `napi_value` representing the +- `[in] args`: Vector of JavaScript values as `napi_value` representing the arguments of the function. -Returns a Value representing the JavaScript object returned by the function. +Returns a `Value` representing the JavaScript value returned by the function. ### Call @@ -156,7 +223,7 @@ Value Call(napi_value recv, size_t argc, const napi_value* args) const; - `[in] args`: Array of JavaScript values as `napi_value` representing the arguments of the function. -Returns a Value representing the JavaScript object returned by the function. +Returns a `Value` representing the JavaScript value returned by the function. ### MakeCallback @@ -170,7 +237,7 @@ Value MakeCallback(napi_value recv, const std::initializer_list& arg - `[in] args`: Initializer list of JavaScript values as `napi_value` representing the arguments of the function. -Returns a Value representing the JavaScript object returned by the function. +Returns a `Value` representing the JavaScript value returned by the function. ### MakeCallback @@ -184,7 +251,7 @@ Value MakeCallback(napi_value recv, const std::vector& args) const; - `[in] args`: List of JavaScript values as `napi_value` representing the arguments of the function. -Returns a Value representing the JavaScript object returned by the function. +Returns a `Value` representing the JavaScript value returned by the function. ### MakeCallback @@ -199,50 +266,7 @@ Value MakeCallback(napi_value recv, size_t argc, const napi_value* args) const; - `[in] args`: Array of JavaScript values as `napi_value` representing the arguments of the function. -Returns a Value representing the JavaScript object returned by the function. - -### New - -Creates a new JavaScript value from one that represents the constructor for the -object. - -```cpp -Object New(const std::initializer_list& args) const; -``` - -- `[in] args`: Initializer list of JavaScript values as `napi_value` representing -the arguments of the contructor function. - -Returns a new JavaScript object. - -### New - -Creates a new JavaScript value from one that represents the constructor for the -object. - -```cpp -Object New(const std::vector& args) const; -``` - -- `[in] args`: List of JavaScript values as `napi_value` representing the -arguments of the constructor function. - -Returns a new JavaScript object. - -### New - -Creates a new JavaScript value from one that represents the constructor for the -object. - -```cpp -Object New(size_t argc, const napi_value* args) const; -``` - -- `[in] argc`: The number of the arguments passed to the contructor function. -- `[in] args`: Array of JavaScript values as `napi_value` representing the -arguments of the constructor function. - -Returns a new JavaScript object. +Returns a `Value` representing the JavaScript value returned by the function. ## Operator @@ -252,4 +276,4 @@ Value operator ()(const std::initializer_list& args) const; - `[in] args`: Initializer list of JavaScript values as `napi_value`. -Returns a Value representing the JavaScript object returned by the function. +Returns a `Value` representing the JavaScript value returned by the function. From ab4d8a6f99255dab01554101b37281f2b5525613 Mon Sep 17 00:00:00 2001 From: NickNaso Date: Tue, 7 Aug 2018 20:00:32 +0200 Subject: [PATCH 04/13] Added function referercne documentation --- doc/function_reference.md | 154 ++++++++++++++++++++++++++------------ 1 file changed, 106 insertions(+), 48 deletions(-) diff --git a/doc/function_reference.md b/doc/function_reference.md index 6c9fe80fe..2d010d458 100644 --- a/doc/function_reference.md +++ b/doc/function_reference.md @@ -1,126 +1,183 @@ # FunctionReference +FunctionReference is a subclass of [Reference](reference.md), and is equivalent to +an instance of `Reference`. This means that a FunctionReference holds a +[Function](function.md), and a count of the number of references to that Function. +When the count is greater than 0, a FunctionReference is not eligible for garbage +collection. This ensures that the Function will remain accessible, even if the +original reference to it is no longer available. +FunctionReference allows to call the referenced JavaScript function object from +a native add-on with two different methods: `Call` and `MackeCallback`. + +The `FunctionReference` class inherits its behavior from the `Reference` class +(for more info see: [Reference](reference.md)). + ## Methods -### Constructor +### Weak -Creates a new +Creates a "weak" reference to the value, in that the initial count of number of +references is set to 0. ```cpp -FunctionReference(); +static FunctionReference Weak(const Function& value); +``` + +- `[in] value`: The value which is to be referenced. + +Returns the newly created reference. + +### Persistent + +Creates a "persistent" reference to the value, in that the initial count of +number of references is set to 1. + +```cpp +static FunctionReference Persistent(const Function& value); ``` -- `[in] Env`: The environment in which to construct the +- `[in] value`: The value which is to be referenced. -Returns a new +Returns the newly created reference. ### Constructor -Creates a new +Creates a new empty instance of `FunctionReference`. + +```cpp +FunctionReference(); +``` + +### Constructor + +Creates a new instance of the `FunctionReference`. ```cpp FunctionReference(napi_env env, napi_ref ref); ``` -- `[in] Env`: The environment in which to construct the +- `[in] env`: The environment in which to construct the FunctionReference object. +- `[in] ref`: The N-API reference to be held by the FunctionReference. -Returns a new +Returns a newly created `FunctionReference` object. -### Call +### New -Creates a new +Creates a new JavaScript value from one that represents the constructor for the +object. ```cpp -Napi::Value Call(const std::initializer_list& args) const; +Object New(const std::initializer_list& args) const; ``` -- `[in] Env`: The environment in which to construct the +- `[in] args`: Initializer list of JavaScript values as napi_value representing +the arguments of the contructor function. -Returns a new +Returns a new JavaScript object. -### Call +### New -Creates a new +Creates a new JavaScript value from one that represents the constructor for the +object. ```cpp -Napi::Value Call(const std::vector& args) const; +Object New(const std::vector& args) const; ``` -- `[in] Env`: The environment in which to construct the +- `[in] args`: Vector of JavaScript values as napi_value representing the +arguments of the constructor function. -Returns a new +Returns a new JavaScript object. ### Call -Creates a new +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 Call(const std::initializer_list& args) const; ``` -- `[in] Env`: The environment in which to construct the +- `[in] args`: Initializer list of JavaScript values as `napi_value` representing +the arguments of the referenced function. -Returns a new +Returns a Value representing the JavaScript object returned by the referenced +function. ### Call -Creates a new +Calls a referenced Javascript function from a native add-on. ```cpp -Napi::Value Call(napi_value recv, const std::vector& args) const; +Napi::Value Call(const std::vector& args) const; ``` -- `[in] Env`: The environment in which to construct the +- `[in] args`: Vector of JavaScript values as `napi_value` representing the +arguments of the referenced function. -Returns a new +Returns a Value representing the JavaScript object returned by the referenced +function. -### MakeCallback +### Call -Creates a new +Calls a referenced Javascript function from a native add-on. ```cpp -Napi::Value MakeCallback(napi_value recv, const std::initializer_list& args) const; +Napi::Value Call(napi_value recv, const std::initializer_list& args) const; ``` -- `[in] Env`: The environment in which to construct the +- `[in] recv`: The `this` object passed to the referenced function when it's called. +- `[in] args`: Initializer list of JavaScript values as `napi_value` representing +the arguments of the referenced function. -Returns a new +Returns a Value representing the JavaScript object returned by the referenced +function. -### MakeCallback +### Call -Creates a new +Calls a referenced Javascript function from a native add-on. ```cpp -Napi::Value MakeCallback(napi_value recv, const std::vector& args) const; +Napi::Value Call(napi_value recv, const std::vector& args) const; ``` -- `[in] Env`: The environment in which to construct the +- `[in] recv`: The `this` object passed to the referenced function when it's called. +- `[in] args`: Vector of JavaScript values as `napi_value` representing the +arguments of the referenced function. -Returns a new +Returns a Value representing the JavaScript object returned by the referenced +function. -### New +### MakeCallback -Creates a new +Calls a referenced Javascript function from a native add-on after an asynchronous +operation. ```cpp -Object New(const std::initializer_list& args) const; +Napi::Value MakeCallback(napi_value recv, const std::initializer_list& args) const; ``` -- `[in] Env`: The environment in which to construct the +- `[in] recv`: The `this` object passed to the referenced function when it's called. +- `[in] args`: Initializer list of JavaScript values as `napi_value` representing +the arguments of the referenced function. -Returns a new +Returns a Value representing the JavaScript object returned by the referenced +function. -### New +### MakeCallback -Creates a new +Calls a referenced Javascript function from a native add-on after an asynchronous +operation. ```cpp -Object New(const std::vector& args) const; +Napi::Value MakeCallback(napi_value recv, const std::vector& args) const; ``` -- `[in] Env`: The environment in which to construct the +- `[in] recv`: The `this` object passed to the referenced function when it's called. +- `[in] args`: Vector of JavaScript values as `napi_value` representing the +arguments of the referenced function. -Returns a new +Returns a Value representing the JavaScript object returned by the referenced +function. ## Operator @@ -128,6 +185,7 @@ Returns a new Napi::Value operator ()(const std::initializer_list& args) const; ``` -- `[in] Env`: The environment in which to construct the +- `[in] args`: Initializer list of reference to JavaScript values as `napi_value` -Returns a new +Returns a `Value` representing the JavaScript value returned by the referenced +function. From a8ca2cf5b41b677973b4078db97fc22c74005b39 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Tue, 7 Aug 2018 17:17:10 -0400 Subject: [PATCH 05/13] squash: add some suggested tweaks. --- doc/function.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/doc/function.md b/doc/function.md index 7ab1e0711..50783978a 100644 --- a/doc/function.md +++ b/doc/function.md @@ -1,9 +1,12 @@ # Function The **Function** class provides a set of methods to create a function object in -native code and consequently calling it back from JavaScript. -The created function is not automatically visible from script, instead it needs to -be part of the add-on's module exports. +native code that can later be called from JavaScript. The created function is not +automatically visible from JavaScript, instead it needs to be part of the add-on's +module exports or be returned by one of the modules exported functions. + +In addition the `Function` class also provides methods that can be used to call +functions that were created in JavaScript and passed to the native. The `Function` class inherits its behavior from the `Object` class (for more info see: [Object](object.md)). @@ -40,7 +43,7 @@ add-on with two different methods: `Call` and `MackeCallback`. The API of these two methods are very similar, but they are used in different context. `MakeCallback` method is used to call from native code back into JavaScript after returning from an [asynchronous operation](async_operations.md) and in general in -all sistuations which don't have an existing JavaScript function on the stack. +situations which don't have an existing JavaScript function on the stack. `Call` method is used when there is already a JavaScript function on the stack (for example when running a natice method called from JavaScript). From 9469a0023d7f5b6edf789ba0fee214d888eb02fc Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Tue, 7 Aug 2018 17:20:09 -0400 Subject: [PATCH 06/13] squash: add suggested tweaks --- doc/function_reference.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/doc/function_reference.md b/doc/function_reference.md index 2d010d458..96b835e7e 100644 --- a/doc/function_reference.md +++ b/doc/function_reference.md @@ -6,8 +6,10 @@ an instance of `Reference`. This means that a FunctionReference holds When the count is greater than 0, a FunctionReference is not eligible for garbage collection. This ensures that the Function will remain accessible, even if the original reference to it is no longer available. -FunctionReference allows to call the referenced JavaScript function object from -a native add-on with two different methods: `Call` and `MackeCallback`. +FunctionReference allows the referenced JavaScript function object to be called +from a native add-on with two different methods: `Call` and `MakeCallback`. See +the documentation for [Function](function.md) for when `Call` should be used +instead of `MakeCallback` and vice-versa. The `FunctionReference` class inherits its behavior from the `Reference` class (for more info see: [Reference](reference.md)). From a09045bbd34fc5751e539c4109d13ca032e87764 Mon Sep 17 00:00:00 2001 From: Nicola Del Gobbo Date: Tue, 7 Aug 2018 23:30:32 +0200 Subject: [PATCH 07/13] Typo natice to native --- doc/function.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/function.md b/doc/function.md index 50783978a..788fba962 100644 --- a/doc/function.md +++ b/doc/function.md @@ -45,7 +45,7 @@ The API of these two methods are very similar, but they are used in different co returning from an [asynchronous operation](async_operations.md) and in general in situations which don't have an existing JavaScript function on the stack. `Call` method is used when there is already a JavaScript function on the stack -(for example when running a natice method called from JavaScript). +(for example when running a native method called from JavaScript). ## Methods From 8b3dbd8a953f1dcb664b9bf0434409616d65d48a Mon Sep 17 00:00:00 2001 From: NickNaso Date: Thu, 9 Aug 2018 15:16:09 +0200 Subject: [PATCH 08/13] Just addressed changes requested after rview --- doc/function.md | 72 +++++++++++++++++++-------------------- doc/function_reference.md | 48 +++++++++++++------------- 2 files changed, 59 insertions(+), 61 deletions(-) diff --git a/doc/function.md b/doc/function.md index 788fba962..3e2bc908f 100644 --- a/doc/function.md +++ b/doc/function.md @@ -1,12 +1,12 @@ # Function -The **Function** class provides a set of methods to create a function object in +The **Function** class provides a set of methods for creating a function object in native code that can later be called from JavaScript. The created function is not -automatically visible from JavaScript, instead it needs to be part of the add-on's -module exports or be returned by one of the modules exported functions. +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 -functions that were created in JavaScript and passed to the native. +functions that were created in JavaScript and passed to the native add-on. The `Function` class inherits its behavior from the `Object` class (for more info see: [Object](object.md)). @@ -38,14 +38,14 @@ const addon = require('./addon'); addon.fn(); ``` -The `Function` class allows to call a JavaScript function object from a native -add-on with two different methods: `Call` and `MackeCallback`. -The API of these two methods are very similar, but they are used in different context. -`MakeCallback` method is used to call from native code back into JavaScript after -returning from an [asynchronous operation](async_operations.md) and in general in -situations which don't have an existing JavaScript function on the stack. -`Call` method is used when there is already a JavaScript function on the stack -(for example when running a native method called from JavaScript). +With the `Function` class it is possible to call a JavaScript function object +from a native add-on with two different methods: `Call` and `MakeCallback`. +The API of these two methods is very similar, but they are used in different +context. The `MakeCallback` method is used to call from native code back into +JavaScript after returning from an [asynchronous operation](async_operations.md) +and in general in situations which don't have an existing JavaScript function on +the stack. The `Call` method is used when there is already a JavaScript function +on the stack (for example when running a native method called from JavaScript). ## Methods @@ -108,7 +108,7 @@ Creates a new JavaScript value from one that represents the constructor for the object. ```cpp -Object New(const std::initializer_list& args) const; +Napi::Object 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 -Object New(const std::vector& args) const; +Napi::Object 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 -Object New(size_t argc, const napi_value* args) const; +Napi::Object New(size_t argc, const napi_value* args) const; ``` - `[in] argc`: The number of the arguments passed to the contructor function. @@ -150,75 +150,75 @@ Returns a new JavaScript object. Calls a Javascript function from a native add-on. ```cpp -Value Call(const std::initializer_list& args) const; +Napi::Value Call(const std::initializer_list& args) const; ``` - `[in] args`: Initializer list of JavaScript values as `napi_value` representing the arguments of the function. -Returns a Value representing the JavaScript object returned by the function. +Returns a `Napi::Value` representing the JavaScript value returned by the function. ### Call -Calls a Javascript function from a native add-on. +Calls a JavaScript function from a native add-on. ```cpp -Value Call(const std::vector& args) const; +Napi::Value Call(const std::vector& args) const; ``` - `[in] args`: Vector of JavaScript values as `napi_value` representing the arguments of the function. -Returns a `Value` representing the JavaScript value returned by the function. +Returns a `Napi::Value` representing the JavaScript value returned by the function. ### Call Calls a Javascript function from a native add-on. ```cpp -Value Call(size_t argc, const napi_value* args) const; +Napi::Value Call(size_t argc, const napi_value* args) const; ``` - `[in] argc`: The number of the arguments passed to the function. - `[in] args`: Array of JavaScript values as `napi_value` representing the arguments of the function. -Returns a `Value` representing the JavaScript value returned by the function. +Returns a `Napi::Value` representing the JavaScript value returned by the function. ### Call Calls a Javascript function from a native add-on. ```cpp -Value Call(napi_value recv, const std::initializer_list& args) const; +Napi::Value Call(napi_value recv, const std::initializer_list& args) const; ``` - `[in] recv`: The `this` object passed to the called function. - `[in] args`: Initializer list of JavaScript values as `napi_value` representing the arguments of the function. -Returns a `Value` representing the JavaScript value returned by the function. +Returns a `Napi::Value` representing the JavaScript value returned by the function. ### Call Calls a Javascript function from a native add-on. ```cpp -Value Call(napi_value recv, const std::vector& args) const; +Napi::Value Call(napi_value recv, const std::vector& args) const; ``` - `[in] recv`: The `this` object passed to the called function. - `[in] args`: Vector of JavaScript values as `napi_value` representing the arguments of the function. -Returns a `Value` representing the JavaScript value returned by the function. +Returns a `Napi::Value` representing the JavaScript value returned by the function. ### Call Calls a Javascript function from a native add-on. ```cpp -Value Call(napi_value recv, size_t argc, const napi_value* args) const; +Napi::Value Call(napi_value recv, size_t argc, const napi_value* args) const; ``` - `[in] recv`: The `this` object passed to the called function. @@ -226,42 +226,42 @@ Value Call(napi_value recv, size_t argc, const napi_value* args) const; - `[in] args`: Array of JavaScript values as `napi_value` representing the arguments of the function. -Returns a `Value` representing the JavaScript value returned by the function. +Returns a `Napi::Value` representing the JavaScript value returned by the function. ### MakeCallback Calls a Javascript function from a native add-on after an asynchronous operation. ```cpp -Value MakeCallback(napi_value recv, const std::initializer_list& args) const; +Napi::Value MakeCallback(napi_value recv, const std::initializer_list& args) const; ``` - `[in] recv`: The `this` object passed to the called function. - `[in] args`: Initializer list of JavaScript values as `napi_value` representing the arguments of the function. -Returns a `Value` representing the JavaScript value returned by the function. +Returns a `Napi::Value` representing the JavaScript value returned by the function. ### MakeCallback Calls a Javascript function from a native add-on after an asynchronous operation. ```cpp -Value MakeCallback(napi_value recv, const std::vector& args) const; +Napi::Value MakeCallback(napi_value recv, const std::vector& args) const; ``` - `[in] recv`: The `this` object passed to the called function. - `[in] args`: List of JavaScript values as `napi_value` representing the arguments of the function. -Returns a `Value` representing the JavaScript value returned by the function. +Returns a `Napi::Value` representing the JavaScript value returned by the function. ### MakeCallback Calls a Javascript function from a native add-on after an asynchronous operation. ```cpp -Value MakeCallback(napi_value recv, size_t argc, const napi_value* args) const; +Napi::Value MakeCallback(napi_value recv, size_t argc, const napi_value* args) const; ``` - `[in] recv`: The `this` object passed to the called function. @@ -269,14 +269,14 @@ Value MakeCallback(napi_value recv, size_t argc, const napi_value* args) const; - `[in] args`: Array of JavaScript values as `napi_value` representing the arguments of the function. -Returns a `Value` representing the JavaScript value returned by the function. +Returns a `Napi::Value` representing the JavaScript value returned by the function. ## Operator ```cpp -Value operator ()(const std::initializer_list& args) const; +Napi::Value operator ()(const std::initializer_list& args) const; ``` - `[in] args`: Initializer list of JavaScript values as `napi_value`. -Returns a `Value` representing the JavaScript value returned by the function. +Returns a `Napi::Value` representing the JavaScript value returned by the function. diff --git a/doc/function_reference.md b/doc/function_reference.md index 96b835e7e..498095712 100644 --- a/doc/function_reference.md +++ b/doc/function_reference.md @@ -1,24 +1,24 @@ # FunctionReference -FunctionReference is a subclass of [Reference](reference.md), and is equivalent to -an instance of `Reference`. This means that a FunctionReference holds a -[Function](function.md), and a count of the number of references to that Function. -When the count is greater than 0, a FunctionReference is not eligible for garbage -collection. This ensures that the Function will remain accessible, even if the +`FunctionReference` is a subclass of [Reference](reference.md), and is equivalent to +an instance of `Reference`. This means that a FunctionReference holds a +[`Function`](function.md), and a count of the number of references to that `Function`. +When the count is greater than 0, a FunctionReference is not eligible for garbage +collection. This ensures that the `Function` will remain accessible, even if the original reference to it is no longer available. -FunctionReference allows the referenced JavaScript function object to be called +`FunctionReference` allows the referenced JavaScript function object to be called from a native add-on with two different methods: `Call` and `MakeCallback`. See -the documentation for [Function](function.md) for when `Call` should be used +the documentation for [`Function`](function.md) for when `Call` should be used instead of `MakeCallback` and vice-versa. -The `FunctionReference` class inherits its behavior from the `Reference` class +The `FunctionReference` class inherits its behavior from the `Reference` class (for more info see: [Reference](reference.md)). ## Methods ### Weak -Creates a "weak" reference to the value, in that the initial count of number of +Creates a "weak" reference to the value, in that the initial count of number of references is set to 0. ```cpp @@ -31,7 +31,7 @@ Returns the newly created reference. ### Persistent -Creates a "persistent" reference to the value, in that the initial count of +Creates a "persistent" reference to the value, in that the initial count of number of references is set to 1. ```cpp @@ -65,28 +65,26 @@ Returns a newly created `FunctionReference` object. ### New -Creates a new JavaScript value from one that represents the constructor for the -object. +Constructs a new instance by calling the constructor held by this reference. ```cpp -Object New(const std::initializer_list& args) const; +Napi::Object New(const std::initializer_list& args) const; ``` -- `[in] args`: Initializer list of JavaScript values as napi_value representing +- `[in] args`: Initializer list of JavaScript values as napi_value representing the arguments of the contructor function. Returns a new JavaScript object. ### New -Creates a new JavaScript value from one that represents the constructor for the -object. +Constructs a new instance by calling the constructor held by this reference. ```cpp -Object New(const std::vector& args) const; +Napi::Object New(const std::vector& args) const; ``` -- `[in] args`: Vector of JavaScript values as napi_value representing the +- `[in] args`: Vector of JavaScript values as napi_value representing the arguments of the constructor function. Returns a new JavaScript object. @@ -102,7 +100,7 @@ Napi::Value Call(const std::initializer_list& args) const; - `[in] args`: Initializer list of JavaScript values as `napi_value` representing the arguments of the referenced function. -Returns a Value representing the JavaScript object returned by the referenced +Returns a `Napi::Value` representing the JavaScript object returned by the referenced function. ### Call @@ -116,7 +114,7 @@ Napi::Value Call(const std::vector& args) const; - `[in] args`: Vector of JavaScript values as `napi_value` representing the arguments of the referenced function. -Returns a Value representing the JavaScript object returned by the referenced +Returns a `Napi::Value` representing the JavaScript object returned by the referenced function. ### Call @@ -131,7 +129,7 @@ Napi::Value Call(napi_value recv, const std::initializer_list& args) - `[in] args`: Initializer list of JavaScript values as `napi_value` representing the arguments of the referenced function. -Returns a Value representing the JavaScript object returned by the referenced +Returns a `Napi::Value` representing the JavaScript object returned by the referenced function. ### Call @@ -146,7 +144,7 @@ Napi::Value Call(napi_value recv, const std::vector& args) const; - `[in] args`: Vector of JavaScript values as `napi_value` representing the arguments of the referenced function. -Returns a Value representing the JavaScript object returned by the referenced +Returns a `Napi::Value` representing the JavaScript object returned by the referenced function. ### MakeCallback @@ -162,7 +160,7 @@ Napi::Value MakeCallback(napi_value recv, const std::initializer_list& args) c - `[in] args`: Vector of JavaScript values as `napi_value` representing the arguments of the referenced function. -Returns a Value representing the JavaScript object returned by the referenced +Returns a `Napi::Value` representing the JavaScript object returned by the referenced function. ## Operator @@ -189,5 +187,5 @@ Napi::Value operator ()(const std::initializer_list& args) const; - `[in] args`: Initializer list of reference to JavaScript values as `napi_value` -Returns a `Value` representing the JavaScript value returned by the referenced +Returns a `Napi::Value` representing the JavaScript value returned by the referenced function. From 6cf54c58987c3f766f6f7ea4fad400172d4404c9 Mon Sep 17 00:00:00 2001 From: NickNaso Date: Tue, 21 Aug 2018 22:42:42 +0200 Subject: [PATCH 09/13] Some little fix after review --- doc/function.md | 8 ++++---- doc/function_reference.md | 14 +++++++------- 2 files changed, 11 insertions(+), 11 deletions(-) diff --git a/doc/function.md b/doc/function.md index 3e2bc908f..00a2d660d 100644 --- a/doc/function.md +++ b/doc/function.md @@ -6,7 +6,7 @@ automatically visible from JavaScript. Instead it needs to be part of the add-on 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 -functions that were created in JavaScript and passed to the native add-on. +functions that were created in JavaScript and passed to the native add-on. The `Function` class inherits its behavior from the `Object` class (for more info see: [Object](object.md)). @@ -41,7 +41,7 @@ addon.fn(); With the `Function` class it is possible to call a JavaScript function object from a native add-on with two different methods: `Call` and `MakeCallback`. The API of these two methods is very similar, but they are used in different -context. The `MakeCallback` method is used to call from native code back into +contexts. The `MakeCallback` method is used to call from native code back into JavaScript after returning from an [asynchronous operation](async_operations.md) and in general in situations which don't have an existing JavaScript function on the stack. The `Call` method is used when there is already a JavaScript function @@ -66,7 +66,7 @@ Function(napi_env env, napi_value value); ``` - `[in] env`: The `napi_env` environment in which to construct the Value object. -- `[in] value`: The `napi_value` which is handle for a JavaScript function. +- `[in] value`: The `napi_value` which is a handle for a JavaScript function. Returns a non-empty `Function` instance. @@ -79,7 +79,7 @@ template static 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 Function object. +- `[in] env`: The `napi_env` environment in which to construct the `Function` object. - `[in] cb`: Object that implements `Callable`. - `[in] utf8name`: Null-terminated string to be used as the name of the function. - `[in] data`: User-provided data context. This will be passed back into the diff --git a/doc/function_reference.md b/doc/function_reference.md index 498095712..8aefa3f53 100644 --- a/doc/function_reference.md +++ b/doc/function_reference.md @@ -1,12 +1,12 @@ # FunctionReference `FunctionReference` is a subclass of [Reference](reference.md), and is equivalent to -an instance of `Reference`. This means that a FunctionReference holds a +an instance of `Reference`. This means that a `FunctionReference` holds a [`Function`](function.md), and a count of the number of references to that `Function`. -When the count is greater than 0, a FunctionReference is not eligible for garbage +When the count is greater than 0, a `FunctionReference` is not eligible for garbage collection. This ensures that the `Function` will remain accessible, even if the original reference to it is no longer available. -`FunctionReference` allows the referenced JavaScript function object to be called +`FunctionReference` allows the referenced JavaScript function object to be called from a native add-on with two different methods: `Call` and `MakeCallback`. See the documentation for [`Function`](function.md) for when `Call` should be used instead of `MakeCallback` and vice-versa. @@ -18,8 +18,8 @@ The `FunctionReference` class inherits its behavior from the `Reference` class ### Weak -Creates a "weak" reference to the value, in that the initial count of number of -references is set to 0. +Creates a "weak" reference to the value, in that the initial reference count is +set to 0. ```cpp static FunctionReference Weak(const Function& value); @@ -71,7 +71,7 @@ Constructs a new instance by calling the constructor held by this reference. Napi::Object New(const std::initializer_list& args) const; ``` -- `[in] args`: Initializer list of JavaScript values as napi_value representing +- `[in] args`: Initializer list of JavaScript values as `napi_value` representing the arguments of the contructor function. Returns a new JavaScript object. @@ -84,7 +84,7 @@ Constructs a new instance by calling the constructor held by this reference. Napi::Object New(const std::vector& args) const; ``` -- `[in] args`: Vector of JavaScript values as napi_value representing the +- `[in] args`: Vector of JavaScript values as `napi_value` representing the arguments of the constructor function. Returns a new JavaScript object. From be415324fa976baddf0faa94daab1abddc394521 Mon Sep 17 00:00:00 2001 From: Nicola Del Gobbo Date: Wed, 22 Aug 2018 23:46:17 +0200 Subject: [PATCH 10/13] Missing corrections after last review --- doc/function_reference.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/function_reference.md b/doc/function_reference.md index 8aefa3f53..22fcf3e5c 100644 --- a/doc/function_reference.md +++ b/doc/function_reference.md @@ -31,8 +31,8 @@ Returns the newly created reference. ### Persistent -Creates a "persistent" reference to the value, in that the initial count of -number of references is set to 1. +Creates a "persistent" reference to the value, in that the initial reference +count is set to 1. ```cpp static FunctionReference Persistent(const Function& value); From 6bdfc5687a892ddaabe303eb8938bf3daebcbea0 Mon Sep 17 00:00:00 2001 From: NickNaso Date: Thu, 23 Aug 2018 23:20:39 +0200 Subject: [PATCH 11/13] Added missing backticks --- doc/function.md | 4 ++-- doc/function_reference.md | 6 +++--- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/function.md b/doc/function.md index 00a2d660d..7c3cbbabb 100644 --- a/doc/function.md +++ b/doc/function.md @@ -65,7 +65,7 @@ Creates a new instance of the `Function` object. Function(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 `Function` object. - `[in] value`: The `napi_value` which is a handle for a JavaScript function. Returns a non-empty `Function` instance. @@ -94,7 +94,7 @@ template static 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 Function object. +- `[in] env`: The `napi_env` environment in which to construct the `Function` object. - `[in] cb`: Object that implements `Callable`. - `[in] utf8name`: String to be used as the name of the function. - `[in] data`: User-provided data context. This will be passed back into the diff --git a/doc/function_reference.md b/doc/function_reference.md index 22fcf3e5c..006f3a84d 100644 --- a/doc/function_reference.md +++ b/doc/function_reference.md @@ -12,7 +12,7 @@ the documentation for [`Function`](function.md) for when `Call` should be used instead of `MakeCallback` and vice-versa. The `FunctionReference` class inherits its behavior from the `Reference` class -(for more info see: [Reference](reference.md)). +(for more info see: [`Reference`](reference.md)). ## Methods @@ -58,8 +58,8 @@ Creates a new instance of the `FunctionReference`. FunctionReference(napi_env env, napi_ref ref); ``` -- `[in] env`: The environment in which to construct the FunctionReference object. -- `[in] ref`: The N-API reference to be held by the FunctionReference. +- `[in] env`: The environment in which to construct the `FunctionReference` object. +- `[in] ref`: The N-API reference to be held by the `FunctionReference`. Returns a newly created `FunctionReference` object. From fcc61a3e28c6c7949ebfac40d68801e5cc766fef Mon Sep 17 00:00:00 2001 From: NickNaso Date: Fri, 24 Aug 2018 17:32:46 +0200 Subject: [PATCH 12/13] Added backticks --- doc/function.md | 2 +- doc/function_reference.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/function.md b/doc/function.md index 7c3cbbabb..302aec9fa 100644 --- a/doc/function.md +++ b/doc/function.md @@ -9,7 +9,7 @@ In addition the `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 `Function` class inherits its behavior from the `Object` class (for more info -see: [Object](object.md)). +see: [`Object`](object.md)). ## Example diff --git a/doc/function_reference.md b/doc/function_reference.md index 006f3a84d..d590dade2 100644 --- a/doc/function_reference.md +++ b/doc/function_reference.md @@ -1,6 +1,6 @@ # FunctionReference -`FunctionReference` is a subclass of [Reference](reference.md), and is equivalent to +`FunctionReference` is a subclass of [`Reference`](reference.md), and is equivalent to an instance of `Reference`. This means that a `FunctionReference` holds a [`Function`](function.md), and a count of the number of references to that `Function`. When the count is greater than 0, a `FunctionReference` is not eligible for garbage From 390ecd1ce32acfeeecccecc2756592bc510f1ed2 Mon Sep 17 00:00:00 2001 From: NickNaso Date: Thu, 30 Aug 2018 17:37:14 +0200 Subject: [PATCH 13/13] Added missing namespace --- doc/function.md | 26 +++++++++++++------------- doc/function_reference.md | 37 +++++++++++++++++++------------------ 2 files changed, 32 insertions(+), 31 deletions(-) diff --git a/doc/function.md b/doc/function.md index 302aec9fa..ca85ef05a 100644 --- a/doc/function.md +++ b/doc/function.md @@ -1,6 +1,6 @@ # Function -The **Function** class provides a set of methods for creating a function object in +The `Napi::Function` class provides a set of methods for creating a function object in native code that can later be called from JavaScript. The created function is not 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. @@ -8,8 +8,8 @@ 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 functions that were created in JavaScript and passed to the native add-on. -The `Function` class inherits its behavior from the `Object` class (for more info -see: [`Object`](object.md)). +The `Napi::Function` class inherits its behavior from the `Napi::Object` class (for more info +see: [`Napi::Object`](object.md)). ## Example @@ -38,7 +38,7 @@ const addon = require('./addon'); addon.fn(); ``` -With the `Function` class it is possible to call a JavaScript function object +With the `Napi::Function` class it is possible to call a JavaScript function object from a native add-on with two different methods: `Call` and `MakeCallback`. The API of these two methods is very similar, but they are used in different contexts. The `MakeCallback` method is used to call from native code back into @@ -51,7 +51,7 @@ on the stack (for example when running a native method called from JavaScript). ### Constructor -Creates a new empty instance of `Function`. +Creates a new empty instance of `Napi::Function`. ```cpp Function(); @@ -59,33 +59,33 @@ Function(); ### Constructor -Creates a new instance of the `Function` object. +Creates a new instance of the `Napi::Function` object. ```cpp Function(napi_env env, napi_value value); ``` -- `[in] env`: The `napi_env` environment in which to construct the `Function` object. +- `[in] env`: The `napi_env` environment in which to construct the `Napi::Function` object. - `[in] value`: The `napi_value` which is a handle for a JavaScript function. -Returns a non-empty `Function` instance. +Returns a non-empty `Napi::Function` instance. ### New -Creates an instance of a `Function` object. +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); ``` -- `[in] env`: The `napi_env` environment in which to construct the `Function` object. +- `[in] env`: The `napi_env` environment in which to construct the `Napi::Function` object. - `[in] cb`: Object that implements `Callable`. - `[in] utf8name`: Null-terminated string to be used as the name of the function. - `[in] data`: User-provided data context. This will be passed back into the function when invoked later. -Returns an instance of a `Function` object. +Returns an instance of a `Napi::Function` object. ### New @@ -94,13 +94,13 @@ template static 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 `Function` object. +- `[in] env`: The `napi_env` environment in which to construct the `Napi::Function` object. - `[in] cb`: Object that implements `Callable`. - `[in] utf8name`: String to be used as the name of the function. - `[in] data`: User-provided data context. This will be passed back into the function when invoked later. -Returns an instance of a `Function` object. +Returns an instance of a `Napi::Function` object. ### New diff --git a/doc/function_reference.md b/doc/function_reference.md index d590dade2..9552dee7d 100644 --- a/doc/function_reference.md +++ b/doc/function_reference.md @@ -1,18 +1,19 @@ # FunctionReference -`FunctionReference` is a subclass of [`Reference`](reference.md), and is equivalent to -an instance of `Reference`. This means that a `FunctionReference` holds a -[`Function`](function.md), and a count of the number of references to that `Function`. -When the count is greater than 0, a `FunctionReference` is not eligible for garbage -collection. This ensures that the `Function` will remain accessible, even if the -original reference to it is no longer available. -`FunctionReference` allows the referenced JavaScript function object to be called -from a native add-on with two different methods: `Call` and `MakeCallback`. See -the documentation for [`Function`](function.md) for when `Call` should be used -instead of `MakeCallback` and vice-versa. - -The `FunctionReference` class inherits its behavior from the `Reference` class -(for more info see: [`Reference`](reference.md)). +`Napi::FunctionReference` is a subclass of [`Napi::Reference`](reference.md), and +is equivalent to an instance of `Napi::Reference`. This means +that a `Napi::FunctionReference` holds a [`Napi::Function`](function.md), and a +count of the number of references to that `Napi::Function`. When the count is +greater than 0, a `Napi::FunctionReference` is not eligible for garbage collection. +This ensures that the `Function` will remain accessible, even if the original +reference to it is no longer available. +`Napi::FunctionReference` allows the referenced JavaScript function object to be +called from a native add-on with two different methods: `Call` and `MakeCallback`. +See the documentation for [`Napi::Function`](function.md) for when `Call` should +be used instead of `MakeCallback` and vice-versa. + +The `Napi::FunctionReference` class inherits its behavior from the `Napi::Reference` +class (for more info see: [`Napi::Reference`](reference.md)). ## Methods @@ -44,7 +45,7 @@ Returns the newly created reference. ### Constructor -Creates a new empty instance of `FunctionReference`. +Creates a new empty instance of `Napi::FunctionReference`. ```cpp FunctionReference(); @@ -52,16 +53,16 @@ FunctionReference(); ### Constructor -Creates a new instance of the `FunctionReference`. +Creates a new instance of the `Napi::FunctionReference`. ```cpp FunctionReference(napi_env env, napi_ref ref); ``` -- `[in] env`: The environment in which to construct the `FunctionReference` object. -- `[in] ref`: The N-API reference to be held by the `FunctionReference`. +- `[in] env`: The environment in which to construct the `Napi::FunctionReference` object. +- `[in] ref`: The N-API reference to be held by the `Napi::FunctionReference`. -Returns a newly created `FunctionReference` object. +Returns a newly created `Napi::FunctionReference` object. ### New