From 1b6803073752eae535f44e547d3b12e069681929 Mon Sep 17 00:00:00 2001
From: Andrey Pechkurov <apechkurov@gmail.com>
Date: Thu, 31 Dec 2020 10:29:49 +0300
Subject: [PATCH] doc: improve ALS.enterWith and exit descriptions
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

PR-URL: https://github.com/nodejs/node/pull/36705
Refs: https://github.com/nodejs/node/issues/36683
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Gerhard Stöbich <deb2001-github@yahoo.de>
Reviewed-By: Rich Trott <rtrott@gmail.com>
---
 doc/api/async_hooks.md | 25 +++++++++++++++----------
 1 file changed, 15 insertions(+), 10 deletions(-)

diff --git a/doc/api/async_hooks.md b/doc/api/async_hooks.md
index 08111b67a8507e..d8c3f63c3e876d 100644
--- a/doc/api/async_hooks.md
+++ b/doc/api/async_hooks.md
@@ -1000,7 +1000,7 @@ added:
 -->
 
 Creates a new instance of `AsyncLocalStorage`. Store is only provided within a
-`run` method call.
+`run` or after `enterWith` method call.
 
 ### `asyncLocalStorage.disable()`
 <!-- YAML
@@ -1011,7 +1011,7 @@ added:
 
 This method disables the instance of `AsyncLocalStorage`. All subsequent calls
 to `asyncLocalStorage.getStore()` will return `undefined` until
-`asyncLocalStorage.run()` is called again.
+`asyncLocalStorage.run()` or `asyncLocalStorage.enterWith()` is called again.
 
 When calling `asyncLocalStorage.disable()`, all current contexts linked to the
 instance will be exited.
@@ -1035,7 +1035,8 @@ added:
 
 This method returns the current store.
 If this method is called outside of an asynchronous context initialized by
-calling `asyncLocalStorage.run`, it will return `undefined`.
+calling `asyncLocalStorage.run()` or `asyncLocalStorage.enterWith()`, it will
+return `undefined`.
 
 ### `asyncLocalStorage.enterWith(store)`
 <!-- YAML
@@ -1046,14 +1047,15 @@ added:
 
 * `store` {any}
 
-Calling `asyncLocalStorage.enterWith(store)` will transition into the context
-for the remainder of the current synchronous execution and will persist
-through any following asynchronous calls.
+This method transitions into the context for the remainder of the current
+synchronous execution and then persists the store through any following
+asynchronous calls.
 
 Example:
 
 ```js
 const store = { id: 1 };
+// Replaces previous store with the given store object
 asyncLocalStorage.enterWith(store);
 asyncLocalStorage.getStore(); // Returns the store object
 someAsyncOperation(() => {
@@ -1064,7 +1066,9 @@ someAsyncOperation(() => {
 This transition will continue for the _entire_ synchronous execution.
 This means that if, for example, the context is entered within an event
 handler subsequent event handlers will also run within that context unless
-specifically bound to another context with an `AsyncResource`.
+specifically bound to another context with an `AsyncResource`. That is why
+`run` should be preferred over `enterWith` unless there are strong reasons
+to use the latter method.
 
 ```js
 const store = { id: 1 };
@@ -1130,14 +1134,15 @@ added:
 
 This methods runs a function synchronously outside of a context and return its
 return value. The store is not accessible within the callback function or
-the asynchronous operations created within the callback.
+the asynchronous operations created within the callback, i.e. any `getStore`
+call done within the callback function will always return `undefined`.
 
 Optionally, arguments can be passed to the function. They will be passed to
 the callback function.
 
 If the callback function throws an error, it will be thrown by `exit` too.
-The stacktrace will not be impacted by this call and
-the context will be re-entered.
+The stacktrace will not be impacted by this call and the context will be
+re-entered.
 
 Example: