From 7659fc1a734bd6cf764e311f6d6768c02ba84b9b Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Wed, 14 Nov 2018 14:51:12 -0500 Subject: [PATCH 1/4] doc: better linkage to node-addon-api One of the comments we got at the N-API workshop at NodeConfEU was that we should have a better link to node-addon-api and the docs in the main API docs for N-API. The goal being to help people find node-addon-api and potentially start with the node-addon-api docs instead if they are using C++. This expands and strengthens the link along with a recommendation that starting with the node-addon-api docs might make sense. --- doc/api/n-api.md | 54 +++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 47 insertions(+), 7 deletions(-) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index c976c5e8f060f0..afeb6fbd24c526 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -34,13 +34,53 @@ properties: handling section [Error Handling][]. The N-API is a C API that ensures ABI stability across Node.js versions -and different compiler levels. However, we also understand that a C++ -API can be easier to use in many cases. To support these cases we expect -there to be one or more C++ wrapper modules that provide an inlineable C++ -API. Binaries built with these wrapper modules will depend on the symbols -for the N-API C based functions exported by Node.js. These wrappers are not -part of N-API, nor will they be maintained as part of Node.js. One such -example is: [node-addon-api](https://github.com/nodejs/node-addon-api). +and different compiler levels. **A C++ API can be easier to use +.** To support using C++, the project maintains a +C++ wrapper module called +[node-addon-api](https://github.com/nodejs/node-addon-api). +This wrapper provides an inlineable C++ API. Binaries built +with `node-addon-api` will depend on the symbols for the N-API C-based +functions exported by Node.js. `node-addon-api` is a more +efficient way to write code that calls N-API. Take, for example, the +following `node-addon-api` code. The first section shows the +`node-add-api` code and the section section shows what actually gets +used in the addon. + +```C++ +Object obj = Object::New(env); +obj["foo"] = String::New(env, "bar"); +``` + +```C++ +napi_status status; +napi_value object, string; +status = napi_create_object(env, &object); +if (status != napi_ok) { + napi_throw_error(env, ...); + return; +} + +status = napi_crate_string_utf8(env, "bar", NAPI_AUTO_LENGTH, &string); +if (status != napi_ok) { + napi_throw_error(env, ...); + return; +} + +status = napi_set_named_property(env, object, "foo", string); +if (status != napi_ok) { + napi_throw_error(env, ...); + return; +} +``` + +The end result is that the addon only uses the exported C APIs. As a result, +it still gets the benefits of the ABI stability provided by the C API. +Detailed API documentation for `node-addon-api` is available +[here](https://github.com/nodejs/node-addon-api#api-documentation). + + +When using `node-addon-api` instead of the C APIs, start with the API docs +for `node-addon-api`. ## Implications of ABI Stability From 040e4bbdcab174274f0d8723c9467cdee26af7c0 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Thu, 15 Nov 2018 14:17:41 +0000 Subject: [PATCH 2/4] squash: address comments --- doc/api/n-api.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index afeb6fbd24c526..cebd54b5ae38b2 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -34,8 +34,8 @@ properties: handling section [Error Handling][]. The N-API is a C API that ensures ABI stability across Node.js versions -and different compiler levels. **A C++ API can be easier to use -.** To support using C++, the project maintains a +and different compiler levels. A C++ API can be easier to use +. To support using C++, the project maintains a C++ wrapper module called [node-addon-api](https://github.com/nodejs/node-addon-api). This wrapper provides an inlineable C++ API. Binaries built From 2b1489b0743a96a2d25bbd4178b80e03c8f6be42 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Thu, 15 Nov 2018 14:27:15 -0500 Subject: [PATCH 3/4] squash: address comments --- doc/api/n-api.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index cebd54b5ae38b2..b6c7bf9ab37bbe 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -34,8 +34,8 @@ properties: handling section [Error Handling][]. The N-API is a C API that ensures ABI stability across Node.js versions -and different compiler levels. A C++ API can be easier to use -. To support using C++, the project maintains a +and different compiler levels. A C++ API can be easier to use. +To support using C++, the project maintains a C++ wrapper module called [node-addon-api](https://github.com/nodejs/node-addon-api). This wrapper provides an inlineable C++ API. Binaries built @@ -43,7 +43,7 @@ with `node-addon-api` will depend on the symbols for the N-API C-based functions exported by Node.js. `node-addon-api` is a more efficient way to write code that calls N-API. Take, for example, the following `node-addon-api` code. The first section shows the -`node-add-api` code and the section section shows what actually gets +`node-addon-api` code and the second section shows what actually gets used in the addon. ```C++ @@ -79,7 +79,8 @@ Detailed API documentation for `node-addon-api` is available [here](https://github.com/nodejs/node-addon-api#api-documentation). -When using `node-addon-api` instead of the C APIs, start with the API docs +When using `node-addon-api` instead of the C APIs, start with the API +[docs](https://github.com/nodejs/node-addon-api#api-documentation) for `node-addon-api`. ## Implications of ABI Stability From c0de9f2369b1a306034188a822a1c1a6f4a5d9eb Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Thu, 15 Nov 2018 16:05:21 -0500 Subject: [PATCH 4/4] squash: address comments --- doc/api/n-api.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index b6c7bf9ab37bbe..d59d84ee870d28 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -75,9 +75,6 @@ if (status != napi_ok) { The end result is that the addon only uses the exported C APIs. As a result, it still gets the benefits of the ABI stability provided by the C API. -Detailed API documentation for `node-addon-api` is available -[here](https://github.com/nodejs/node-addon-api#api-documentation). - When using `node-addon-api` instead of the C APIs, start with the API [docs](https://github.com/nodejs/node-addon-api#api-documentation)