From 74c65647a788408cffd302bfd0da6a27e4277542 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Mon, 14 Sep 2020 17:37:30 -0400 Subject: [PATCH 1/9] doc: clarify use of NAPI_EXPERIMENTAL We've had a few questions about APIs not being available which were related to not having specified `NAPI_EXPERIMENTAL`. Add some additional documentation to explain this common issue: Refs: https://github.com/nodejs/node-addon-api/issues/810 Signed-off-by: Michael Dawson --- doc/api/n-api.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index 2f30535b1a4224..53f8116fb852cc 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -261,6 +261,16 @@ listed as supporting a later version. version 1 but continued to evolve until Node.js 8.6.0. The API is different in versions prior to Node.js 8.6.0. We recommend N-API version 3 or later. +For each API documented for N-API, there will be `added in:`, and for APIs +which are stable, `N-API version:`. APIs are directly usable when using +a Node.js version which supports the N-API version shown in `N-API version:` +or higher. When using a Node.js version that does not support the +`N-API version:` listed or if there is no `N-API version:` listed, +then the API will only be available if you include +`#define NAPI_EXPERIMENTAL`. If an API is not available and you are +using a version of Node.js which is later than `added in:` +this is most likely the reason. + The N-APIs associated strictly with accessing ECMAScript features from native code can be found separately in `js_native_api.h` and `js_native_api_types.h`. The APIs defined in these headers are included in `node_api.h` and From e1e01785bf18782cb890e661933cb39f72d3d345 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Thu, 17 Sep 2020 14:37:50 -0400 Subject: [PATCH 2/9] Update doc/api/n-api.md Co-authored-by: Gabriel Schulhof --- doc/api/n-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index 53f8116fb852cc..4c60ba5afd88a2 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -269,7 +269,7 @@ or higher. When using a Node.js version that does not support the then the API will only be available if you include `#define NAPI_EXPERIMENTAL`. If an API is not available and you are using a version of Node.js which is later than `added in:` -this is most likely the reason. +this is most likely the reason for the apparent absence. The N-APIs associated strictly with accessing ECMAScript features from native code can be found separately in `js_native_api.h` and `js_native_api_types.h`. From 36d8e94ecd0a2c58d2d82e6650cd8eecdfe1c0ce Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Thu, 17 Sep 2020 14:38:31 -0400 Subject: [PATCH 3/9] Update doc/api/n-api.md Co-authored-by: Gabriel Schulhof --- doc/api/n-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index 4c60ba5afd88a2..0adcd47d66e06f 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -266,7 +266,7 @@ which are stable, `N-API version:`. APIs are directly usable when using a Node.js version which supports the N-API version shown in `N-API version:` or higher. When using a Node.js version that does not support the `N-API version:` listed or if there is no `N-API version:` listed, -then the API will only be available if you include +then the API will only be available if `#define NAPI_EXPERIMENTAL`. If an API is not available and you are using a version of Node.js which is later than `added in:` this is most likely the reason for the apparent absence. From 9a976c2558a5faa242b7aa7872807051bd0da5a8 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Thu, 17 Sep 2020 14:39:09 -0400 Subject: [PATCH 4/9] Update doc/api/n-api.md Co-authored-by: Gabriel Schulhof --- doc/api/n-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index 0adcd47d66e06f..8e5318756f9a42 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -267,7 +267,7 @@ a Node.js version which supports the N-API version shown in `N-API version:` or higher. When using a Node.js version that does not support the `N-API version:` listed or if there is no `N-API version:` listed, then the API will only be available if -`#define NAPI_EXPERIMENTAL`. If an API is not available and you are +`#define NAPI_EXPERIMENTAL` precedes the inclusion of `node_api.h` or `js_native_api.h`. If an API appears not to be available on using a version of Node.js which is later than `added in:` this is most likely the reason for the apparent absence. From 5c5e4f60f61cc23c87ed772802b3649c41235cb7 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Thu, 17 Sep 2020 14:39:15 -0400 Subject: [PATCH 5/9] Update doc/api/n-api.md Co-authored-by: Gabriel Schulhof --- doc/api/n-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index 8e5318756f9a42..878cf000188885 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -268,7 +268,7 @@ or higher. When using a Node.js version that does not support the `N-API version:` listed or if there is no `N-API version:` listed, then the API will only be available if `#define NAPI_EXPERIMENTAL` precedes the inclusion of `node_api.h` or `js_native_api.h`. If an API appears not to be available on -using a version of Node.js which is later than `added in:` +a version of Node.js which is later than the one shown in `added in:` then this is most likely the reason for the apparent absence. The N-APIs associated strictly with accessing ECMAScript features from native From 34510f4a3549aa24ec7644d9e6481f839a19d827 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Thu, 17 Sep 2020 14:39:42 -0400 Subject: [PATCH 6/9] Update doc/api/n-api.md --- doc/api/n-api.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index 878cf000188885..a4f18a3dfbf20a 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -267,7 +267,8 @@ a Node.js version which supports the N-API version shown in `N-API version:` or higher. When using a Node.js version that does not support the `N-API version:` listed or if there is no `N-API version:` listed, then the API will only be available if -`#define NAPI_EXPERIMENTAL` precedes the inclusion of `node_api.h` or `js_native_api.h`. If an API appears not to be available on +`#define NAPI_EXPERIMENTAL` precedes the inclusion of `node_api.h` +or `js_native_api.h`. If an API appears not to be available on a version of Node.js which is later than the one shown in `added in:` then this is most likely the reason for the apparent absence. From d8d8c9087aef9a982123af27e3b98084aa14fb75 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Fri, 18 Sep 2020 16:08:14 -0400 Subject: [PATCH 7/9] Update doc/api/n-api.md Co-authored-by: Gabriel Schulhof --- doc/api/n-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index a4f18a3dfbf20a..7f62d2670295b1 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -261,7 +261,7 @@ listed as supporting a later version. version 1 but continued to evolve until Node.js 8.6.0. The API is different in versions prior to Node.js 8.6.0. We recommend N-API version 3 or later. -For each API documented for N-API, there will be `added in:`, and for APIs +Each API documented for N-API will have a header named `added in:`, and APIs which are stable, `N-API version:`. APIs are directly usable when using a Node.js version which supports the N-API version shown in `N-API version:` or higher. When using a Node.js version that does not support the From 4ed6bcc8cd1b3a6a753006023e516754e85bf8a7 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Fri, 18 Sep 2020 16:08:31 -0400 Subject: [PATCH 8/9] Update doc/api/n-api.md Co-authored-by: Gabriel Schulhof --- doc/api/n-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index 7f62d2670295b1..09b2605c0effe6 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -262,7 +262,7 @@ version 1 but continued to evolve until Node.js 8.6.0. The API is different in versions prior to Node.js 8.6.0. We recommend N-API version 3 or later. Each API documented for N-API will have a header named `added in:`, and APIs -which are stable, `N-API version:`. APIs are directly usable when using +which are stable will have the additional header `N-API version:`. APIs are directly usable when using a Node.js version which supports the N-API version shown in `N-API version:` or higher. When using a Node.js version that does not support the `N-API version:` listed or if there is no `N-API version:` listed, From 0162f80ecedf77664862fdea58e9fb8440c7d4db Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Fri, 18 Sep 2020 16:41:10 -0400 Subject: [PATCH 9/9] fix linter issues --- doc/api/n-api.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index 09b2605c0effe6..9407d1274bb3b6 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -262,9 +262,10 @@ version 1 but continued to evolve until Node.js 8.6.0. The API is different in versions prior to Node.js 8.6.0. We recommend N-API version 3 or later. Each API documented for N-API will have a header named `added in:`, and APIs -which are stable will have the additional header `N-API version:`. APIs are directly usable when using -a Node.js version which supports the N-API version shown in `N-API version:` -or higher. When using a Node.js version that does not support the +which are stable will have the additional header `N-API version:`. +APIs are directly usable when using a Node.js version which supports +the N-API version shown in `N-API version:` or higher. +When using a Node.js version that does not support the `N-API version:` listed or if there is no `N-API version:` listed, then the API will only be available if `#define NAPI_EXPERIMENTAL` precedes the inclusion of `node_api.h`