1berry/nodejs
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

doc: better linkage to node-addon-api

Browse Source 
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 <thechargingvolcano@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
Reviewed-By: Franziska Hinkelmann <franziska.hinkelmann@gmail.com>
This commit is contained in:
Michael Dawson 2018-11-14 14:51:12 -05:00
parent 6b4e413526
commit a56968698d
1 changed files with 45 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

52
doc/api/n-api.md
View File

@ -34,13 +34,51 @@ properties:
handling section [Error Handling][]. handling section [Error Handling][].
The N-API is a C API that ensures ABI stability across Node.js versions 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++ and different compiler levels. A C++ API can be easier to use.
API can be easier to use in many cases. To support these cases we expect To support using C++, the project maintains a
there to be one or more C++ wrapper modules that provide an inlineable C++ C++ wrapper module called
API. Binaries built with these wrapper modules will depend on the symbols [node-addon-api](https://github.com/nodejs/node-addon-api).
for the N-API C based functions exported by Node.js. These wrappers are not This wrapper provides an inlineable C++ API. Binaries built
part of N-API, nor will they be maintained as part of Node.js. One such with `node-addon-api` will depend on the symbols for the N-API C-based
example is: [node-addon-api](https://github.com/nodejs/node-addon-api). 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 ## Implications of ABI Stability