doc: add clarification for exception behaviour

Document current behaviour where some methods can be called when an exception is pending, while others cannot and explain the behaviour. PR-URL: #25339 Refs: nodejs/abi-stable-node#356 Reviewed-By: Colin Ihrig <[email protected]> Reviewed-By: Anna Henningsen <[email protected]> Reviewed-By: Luigi Pinca <[email protected]>
nodejs · Jan 14, 2019 · 8bc1651 · 8bc1651
1 parent f3d8639
commit 8bc1651
Showing 1 changed file with 9 additions and 0 deletions.
diff --git a/doc/api/n-api.md b/doc/api/n-api.md
@@ -527,6 +527,15 @@ exception is pending and no additional action is required. If the
 instead of simply returning immediately, [`napi_is_exception_pending`][]
 must be called in order to determine if an exception is pending or not.
 
+In many cases when an N-API function is called and an exception is
+already pending, the function will return immediately with a
+`napi_status` of `napi_pending_exception`. However, this is not the case
+for all functions. N-API allows a subset of the functions to be
+called to allow for some minimal cleanup before returning to JavaScript.
+In that case, `napi_status` will reflect the status for the function. It
+will not reflect previous pending exceptions. To avoid confusion, check
+the error status after every function call.
+
 When an exception is pending one of two approaches can be employed.
 
 The first approach is to do any appropriate cleanup and then return so that