doc: Add initial documentation for N-API

Add the initial documentation for the N-API This PR is a result of work in the abi-stable-node repo: https://github.com/nodejs/abi-stable-node/tree/doc, with this PR being the cumulative work on the documentation sections in that repo with the following contributors in alphabetical order: Author: Arunesh Chandra <[email protected]> Author: Gabriel Schulhof <[email protected]> Author: Hitesh Kanwathirtha <[email protected]> Author: Jason Ginchereau <[email protected]> Author: Michael Dawson <[email protected]> Author: Sampson Gao <[email protected]> Author: Taylor Woll <[email protected]> Backport-PR-URL: #19447 PR-URL: #12549 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Jeremiah Senkpiel <[email protected]> Reviewed-By: Colin Ihrig <[email protected]>
nodejs · Apr 16, 2018 · 3e388cf · 3e388cf
1 parent 49d74c6
commit 3e388cf
Show file tree

Hide file tree

Showing 3 changed files with 3,019 additions and 0 deletions.
diff --git a/doc/api/_toc.md b/doc/api/_toc.md
@@ -8,6 +8,7 @@
 * [Assertion Testing](assert.html)
 * [Buffer](buffer.html)
 * [C/C++ Addons](addons.html)
+* [C/C++ Addons - N-API](n-api.html)
 * [Child Processes](child_process.html)
 * [Cluster](cluster.html)
 * [Command Line Options](cli.html)

diff --git a/doc/api/addons.md b/doc/api/addons.md
@@ -215,6 +215,26 @@ Addon developers are recommended to use to keep compatibility between past and
 future releases of V8 and Node.js. See the `nan` [examples][] for an
 illustration of how it can be used.
 
+
+## N-API
+
+> Stability: 1 - Experimental
+
+N-API is an API for building native Addons. It is independent from
+the underlying JavaScript runtime (ex V8) and is maintained as part of
+Node.js itself. This API will be Application Binary Interface (ABI) stable
+across version of Node.js. It is intended to insulate Addons from
+changes in the underlying JavaScript engine and allow modules
+compiled for one version to run on later versions of Node.js without
+recompilation. Addons are built/packaged with the same approach/tools
+outlined in this document (node-gyp, etc.). The only difference is the
+set of APIs that are used by the native code. Instead of using the V8
+or [Native Abstractions for Node.js][] APIs, the functions available
+in the N-API are used.
+
+The functions available and how to use them are documented in the
+section titled [C/C++ Addons - N-API](n-api.html).
+
 ## Addon examples
 
 Following are some example Addons intended to help developers get started. The