From a62c146070c08b3d283f9ba977e144fab742307f Mon Sep 17 00:00:00 2001
From: Michael Dawson <michael_dawson@ca.ibm.com>
Date: Thu, 30 Apr 2020 18:47:10 -0400
Subject: [PATCH 1/4] doc: update napi_async_init documentation

Fixes: https://github.com/nodejs/node/issues/33153

Change documentation to make async_resource required
as opposed to optional in napi-async_init.

Changes over time mean this parameter is required for
proper operation of async hooks (which are still experimental).
This changes the documentation to document what
callers should do. We are doing this only in the doc
in order to avoid a breaking change in N-API. We could
create a new version of the method for which the
parametrer is enforced as mandatory but we should only
do that once async hooks is no longer experimental. In
that case we could deprecate (but not remove this version
of the method).

Signed-off-by: Michael Dawson <michael_dawson@ca.ibm.com>
---
 doc/api/n-api.md | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/doc/api/n-api.md b/doc/api/n-api.md
index 5552aaf57bfcad..ca55d2f6e1d09c 100644
--- a/doc/api/n-api.md
+++ b/doc/api/n-api.md
@@ -4672,7 +4672,7 @@ napi_status napi_async_init(napi_env env,
 ```
 
 * `[in] env`: The environment that the API is invoked under.
-* `[in] async_resource`: An optional object associated with the async work
+* `[in] async_resource`: Object associated with the async work
   that will be passed to possible `async_hooks` [`init` hooks][].
 * `[in] async_resource_name`: Identifier for the kind of resource
   that is being provided for diagnostic information exposed by the
@@ -4681,6 +4681,12 @@ napi_status napi_async_init(napi_env env,
 
 Returns `napi_ok` if the API succeeded.
 
+In order to retain ABI compatibility with previous versions,
+passing `NULL` for `async_resource` will not result in an error, however,
+this will result incorrect operation of async hooks for the
+napi_async_context created. Potential issues include include
+loss of async context when using the AsyncLocalStorage API.
+
 ### napi_async_destroy
 <!-- YAML
 added: v8.6.0

From 218f11030ee5b83dfaec23513bdc24517c5792cb Mon Sep 17 00:00:00 2001
From: Michael Dawson <michael_dawson@ca.ibm.com>
Date: Mon, 4 May 2020 11:45:18 -0400
Subject: [PATCH 2/4] Update doc/api/n-api.md

Co-authored-by: legendecas <legendecas@gmail.com>
---
 doc/api/n-api.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/api/n-api.md b/doc/api/n-api.md
index ca55d2f6e1d09c..b82d918ee13c75 100644
--- a/doc/api/n-api.md
+++ b/doc/api/n-api.md
@@ -4684,7 +4684,7 @@ Returns `napi_ok` if the API succeeded.
 In order to retain ABI compatibility with previous versions,
 passing `NULL` for `async_resource` will not result in an error, however,
 this will result incorrect operation of async hooks for the
-napi_async_context created. Potential issues include include
+napi_async_context created. Potential issues include
 loss of async context when using the AsyncLocalStorage API.
 
 ### napi_async_destroy

From 9d5c4d43b1c050176c9d866be4503b7a5de25cc1 Mon Sep 17 00:00:00 2001
From: Michael Dawson <michael_dawson@ca.ibm.com>
Date: Mon, 4 May 2020 11:50:08 -0400
Subject: [PATCH 3/4] Update doc/api/n-api.md

---
 doc/api/n-api.md | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/doc/api/n-api.md b/doc/api/n-api.md
index b82d918ee13c75..a36c35538e382a 100644
--- a/doc/api/n-api.md
+++ b/doc/api/n-api.md
@@ -4674,6 +4674,11 @@ napi_status napi_async_init(napi_env env,
 * `[in] env`: The environment that the API is invoked under.
 * `[in] async_resource`: Object associated with the async work
   that will be passed to possible `async_hooks` [`init` hooks][].
+  In order to retain ABI compatibility with previous versions,
+  passing `NULL` for `async_resource` will not result in an error, however,
+  this will result incorrect operation of async hooks for the
+  napi_async_context created. Potential issues include
+  loss of async context when using the AsyncLocalStorage API.
 * `[in] async_resource_name`: Identifier for the kind of resource
   that is being provided for diagnostic information exposed by the
   `async_hooks` API.

From ca52b00c010c6015f057edb0973e79d95b0d8c54 Mon Sep 17 00:00:00 2001
From: Michael Dawson <michael_dawson@ca.ibm.com>
Date: Mon, 4 May 2020 11:50:40 -0400
Subject: [PATCH 4/4] Update doc/api/n-api.md

---
 doc/api/n-api.md | 6 ------
 1 file changed, 6 deletions(-)

diff --git a/doc/api/n-api.md b/doc/api/n-api.md
index a36c35538e382a..17d49726fc0c29 100644
--- a/doc/api/n-api.md
+++ b/doc/api/n-api.md
@@ -4686,12 +4686,6 @@ napi_status napi_async_init(napi_env env,
 
 Returns `napi_ok` if the API succeeded.
 
-In order to retain ABI compatibility with previous versions,
-passing `NULL` for `async_resource` will not result in an error, however,
-this will result incorrect operation of async hooks for the
-napi_async_context created. Potential issues include
-loss of async context when using the AsyncLocalStorage API.
-
 ### napi_async_destroy
 <!-- YAML
 added: v8.6.0