doc: clarify use of NAPI_EXPERIMENTAL

mhdawson · addaleax · commit 6669effc4dbb · 2020-09-22T23:48:32.000+02:00
We've had a few questions about APIs not being available which were related to not having specified `NAPI_EXPERIMENTAL`. Add some additional documentation to explain this common issue: Refs: nodejs/node-addon-api#810 Signed-off-by: Michael Dawson <mdawson@devrus.com> PR-URL: #35195 Reviewed-By: Jiawen Geng <technicalcute@gmail.com> Reviewed-By: Gabriel Schulhof <gabriel.schulhof@intel.com> Reviewed-By: Chengzhong Wu <legendecas@gmail.com>
diff --git a/doc/api/n-api.md b/doc/api/n-api.md
@@ -257,6 +257,18 @@ listed as supporting a later version.
 
 \* Indicates that the N-API version was released as experimental
 
+Each API documented for N-API will have a header named `added in:`, and APIs
+which are stable will have the additional header `N-API version:`.
+APIs are directly usable when using a Node.js version which supports
+the N-API version shown in `N-API version:` or higher.
+When using a Node.js version that does not support the
+`N-API version:` listed or if there is no `N-API version:` listed,
+then the API will only be available if
+`#define NAPI_EXPERIMENTAL` precedes the inclusion of `node_api.h`
+or `js_native_api.h`. If an API appears not to be available on
+a version of Node.js which is later than the one shown in `added in:` then
+this is most likely the reason for the apparent absence.
+
 The N-APIs associated strictly with accessing ECMAScript features from native
 code can be found separately in `js_native_api.h` and `js_native_api_types.h`.
 The APIs defined in these headers are included in `node_api.h` and
