From ab4763d117d3fd3585abd0130c34183fe12e7070 Mon Sep 17 00:00:00 2001
From: Gabriel Schulhof <gabriel.schulhof@intel.com>
Date: Thu, 1 Mar 2018 17:44:51 -0500
Subject: [PATCH] n-api: update documentation

Document which APIs work while an exception is pending. This is the
list of all APIs which do not start with `NAPI_PREAMBLE(env)`.

Fixes: https://github.com/nodejs/abi-stable-node/issues/257
PR-URL: https://github.com/nodejs/node/pull/19078
Reviewed-By: Michael Dawson <michael_dawson@ca.ibm.com>
---
 doc/api/n-api.md | 36 ++++++++++++++++++++++++++----------
 1 file changed, 26 insertions(+), 10 deletions(-)

diff --git a/doc/api/n-api.md b/doc/api/n-api.md
index 4c555554405331..2345a14fe4d169 100644
--- a/doc/api/n-api.md
+++ b/doc/api/n-api.md
@@ -277,6 +277,8 @@ valid up until an n-api function is called on the same `env`.
 information as it is not subject to SemVer and may change at any time.
 It is intended only for logging purposes.
 
+This API can be called even if there is a pending JavaScript exception.
+
 
 ### Exceptions
 Any N-API function call may result in a pending JavaScript exception. This is
@@ -502,7 +504,6 @@ Returns `napi_ok` if the API succeeded.
 
 This API returns a JavaScript RangeError with the text provided.
 
-
 #### napi_get_and_clear_last_exception
 <!-- YAML
 added: v8.0.0
@@ -519,6 +520,8 @@ Returns `napi_ok` if the API succeeded.
 
 This API returns true if an exception is pending.
 
+This API can be called even if there is a pending JavaScript exception.
+
 #### napi_is_exception_pending
 <!-- YAML
 added: v8.0.0
@@ -534,6 +537,8 @@ Returns `napi_ok` if the API succeeded.
 
 This API returns true if an exception is pending.
 
+This API can be called even if there is a pending JavaScript exception.
+
 ### Fatal Errors
 
 In the event of an unrecoverable error in a native module, a fatal error can be
@@ -560,6 +565,8 @@ null-terminated.
 
 The function call does not return, the process will be terminated.
 
+This API can be called even if there is a pending JavaScript exception.
+
 ## Object Lifetime management
 
 As N-API calls are made, handles to objects in the heap for the underlying
@@ -680,6 +687,8 @@ Returns `napi_ok` if the API succeeded.
 This API closes the scope passed in. Scopes must be closed in the
 reverse order from which they were created.
 
+This API can be called even if there is a pending JavaScript exception.
+
 #### napi_open_escapable_handle_scope
 <!-- YAML
 added: v8.0.0
@@ -714,6 +723,8 @@ Returns `napi_ok` if the API succeeded.
 This API closes the scope passed in. Scopes must be closed in the
 reverse order from which they were created.
 
+This API can be called even if there is a pending JavaScript exception.
+
 #### napi_escape_handle
 <!-- YAML
 added: v8.0.0
@@ -737,7 +748,10 @@ This API promotes the handle to the JavaScript object so that it is valid
 for the lifetime of the outer scope. It can only be called once per scope.
 If it is called more than once an error will be returned.
 
+This API can be called even if there is a pending JavaScript exception.
+
 ### References to objects with a lifespan longer than that of the native method
+
 In some cases an addon will need to be able to create and reference objects
 with a lifespan longer than that of a single native method invocation. For
 example, to create a constructor and later use that constructor
@@ -812,6 +826,8 @@ Returns `napi_ok` if the API succeeded.
 
 This API deletes the reference passed in.
 
+This API can be called even if there is a pending JavaScript exception.
+
 #### napi_reference_ref
 <!-- YAML
 added: v8.0.0
@@ -830,7 +846,6 @@ Returns `napi_ok` if the API succeeded.
 This API increments the reference count for the reference
 passed in and returns the resulting reference count.
 
-
 #### napi_reference_unref
 <!-- YAML
 added: v8.0.0
@@ -849,7 +864,6 @@ Returns `napi_ok` if the API succeeded.
 This API decrements the reference count for the reference
 passed in and returns the resulting reference count.
 
-
 #### napi_get_reference_value
 <!-- YAML
 added: v8.0.0
@@ -1676,8 +1690,6 @@ This API returns various properties of a typed array.
 *Warning*: Use caution while using this API since the underlying data buffer
 is managed by the VM
 
-
-
 #### napi_get_dataview_info
 <!-- YAML
 added: REPLACEME
@@ -1705,7 +1717,6 @@ Returns `napi_ok` if the API succeeded.
 
 This API returns various properties of a DataView.
 
-
 #### napi_get_value_bool
 <!-- YAML
 added: v8.0.0
@@ -1746,7 +1757,6 @@ in it returns `napi_number_expected`.
 This API returns the C double primitive equivalent of the given JavaScript
 Number.
 
-
 #### napi_get_value_external
 <!-- YAML
 added: v8.0.0
@@ -1808,7 +1818,7 @@ Returns `napi_ok` if the API succeeded. If a non-number `napi_value`
 is passed in it returns `napi_number_expected`.
 
 This API returns the C int64 primitive equivalent of the given
-JavaScript Number
+JavaScript Number.
 
 #### napi_get_value_string_latin1
 <!-- YAML
@@ -2200,8 +2210,6 @@ Returns `napi_ok` if the API succeeded.
 
 This API checks if the Object passsed in is a typed array.
 
-
-
 ### napi_is_dataview
 <!-- YAML
 added: REPLACEME
@@ -3321,6 +3329,8 @@ Returns `napi_ok` if the API succeeded.
 
 This API frees a previously allocated work object.
 
+This API can be called even if there is a pending JavaScript exception.
+
 ### napi_queue_async_work
 <!-- YAML
 added: v8.0.0
@@ -3359,6 +3369,8 @@ the `complete` callback will be invoked with a status value of
 `napi_cancelled`. The work should not be deleted before the `complete`
 callback invocation, even if it has been successfully cancelled.
 
+This API can be called even if there is a pending JavaScript exception.
+
 ## Custom Asynchronous Operations
 The simple asynchronous work APIs above may not be appropriate for every
 scenario. When using any other asynchronous mechanism, the following APIs
@@ -3400,6 +3412,8 @@ napi_status napi_async_destroy(napi_env env,
 
 Returns `napi_ok` if the API succeeded.
 
+This API can be called even if there is a pending JavaScript exception.
+
 ### napi_make_callback
 <!-- YAML
 added: v8.0.0
@@ -3482,6 +3496,8 @@ NAPI_EXTERN napi_status napi_close_callback_scope(napi_env env,
 - `[in] env`: The environment that the API is invoked under.
 - `[in] scope`: The scope to be closed.
 
+This API can be called even if there is a pending JavaScript exception.
+
 ## Version Management
 
 ### napi_get_node_version