doc: Clarify positioning versus N-API #288
Conversation
There was a problem hiding this comment.
So much clearer.
The only thing I'd say is that in the future, it would probably be better to not even reference N-API at all and just say "This is a C++ library for writing Node addons" and only later mentioning that it's built on top of N-API. As a C++ native addon developer, in my ideal world, I don't have to know about anything besides node-addon-api. However, considering this isn't integrated into the core docs and the module docs are incomplete, positioning it relative to N-API seems fine for now.
README.md
Outdated
| provided by Node.js when using C++. It provides a C++ object model | ||
| and exception handling semantics with low overhead. | ||
|
|
||
| N-API is an ABI stale API for building native addons in C++. It is |
There was a problem hiding this comment.
I think you just mean "N-API is a stable API" rather than "N-API is an ABI stale API"
There was a problem hiding this comment.
I think you should also say N-API is a ABI stable C interface provided by Node.js for building native addons... It is not necessary that such addons be written in C++ and saying in C++ muddies the waters a little bit IMO.
There was a problem hiding this comment.
Thanks for catching those 2, will update to address
README.md
Outdated
| provided by Node.js when using C++. It provides a C++ object model | ||
| and exception handling semantics with low overhead. | ||
|
|
||
| N-API is an ABI stale API for building native addons in C++. It is |
There was a problem hiding this comment.
I think you should also say N-API is a ABI stable C interface provided by Node.js for building native addons... It is not necessary that such addons be written in C++ and saying in C++ muddies the waters a little bit IMO.
README.md
Outdated
| **ECMA262 Language Specification**. | ||
| recompilation. | ||
|
|
||
| The node-addon-api module preserves the benefits of the N-API as it consists |
There was a problem hiding this comment.
add ticks around node-addon-api like node-addon-api.
Recommendation:
The
node-addon-apimodule, which is not a part of Node.js, preserves the benefits of the CN-APIby using inlineC++code which only depends on the stable C ABI provided byN-API.
README.md
Outdated
| only of inline code that depends only on the stable API provided by N-API. | ||
| As such, modules built against one version of Node.js using node-addon-api | ||
| should run without having to be rebuilt with newer versions of Node.js. | ||
| As new APIs are added to N-API, node-addon-api must be updated to provide |
There was a problem hiding this comment.
Start a new paragraph at As new APIs are added to...
PR-URL: #288 Reviewed-By: Nicola Del Gobbo <[email protected]>
|
Landed as c2a620d |
PR-URL: nodejs/node-addon-api#288 Reviewed-By: Nicola Del Gobbo <[email protected]>
PR-URL: nodejs/node-addon-api#288 Reviewed-By: Nicola Del Gobbo <[email protected]>
PR-URL: nodejs/node-addon-api#288 Reviewed-By: Nicola Del Gobbo <[email protected]>
PR-URL: nodejs/node-addon-api#288 Reviewed-By: Nicola Del Gobbo <[email protected]>
No description provided.