From c19d6e26a3faf1ae8fd334ce40c02322214e473f Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Wed, 14 Nov 2018 14:51:12 -0500 Subject: [PATCH] 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. PR-URL: https://github.com/nodejs/node/pull/24371 Reviewed-By: Sakthipriyan Vairamani Reviewed-By: Vse Mozhet Byt Reviewed-By: Franziska Hinkelmann --- doc/api/n-api.md | 52 +++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 45 insertions(+), 7 deletions(-) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index 17d6dac0a333e9..91a39ff4835266 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -34,13 +34,51 @@ 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-addon-api` code and the second 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. + +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