doc: document domain.enter() and domain.exit()

Adds the documentation requested in #5017.

1 files changed, 34 insertions, 0 deletions

diff --git a/doc/api/domain.markdown b/doc/api/domain.markdown
index b93c3fcd62..d3b714c85d 100644
--- a/doc/api/domain.markdown
+++ b/doc/api/domain.markdown
@@ -384,6 +384,40 @@ with a single error handler in a single place.
       // with the normal line number and stack message.
     });
 
+### domain.enter()
+
+The `enter` method is plumbing used by the `run`, `bind`, and `intercept`
+methods to set the active domain. It sets `domain.active` and `process.domain`
+to the domain, and implicitly pushes the domain onto the domain stack managed
+by the domain module (see `domain.exit()` for details on the domain stack). The
+call to `enter` delimits the beginning of a chain of asynchronous calls and I/O
+operations bound to a domain.
+
+Calling `enter` changes only the active domain, and does not alter the domain
+itself. `Enter` and `exit` can be called an arbitrary number of times on a
+single domain.
+
+If the domain on which `enter` is called has been disposed, `enter` will return
+without setting the domain.
+
+### domain.exit()
+
+The `exit` method exits the current domain, popping it off the domain stack.
+Any time execution is going to switch to the context of a different chain of
+asynchronous calls, it's important to ensure that the current domain is exited.
+The call to `exit` delimits either the end of or an interruption to the chain
+of asynchronous calls and I/O operations bound to a domain.
+
+If there are multiple, nested domains bound to the current execution context,
+`exit` will exit any domains nested within this domain.
+
+Calling `exit` changes only the active domain, and does not alter the domain
+itself. `Enter` and `exit` can be called an arbitrary number of times on a
+single domain.
+
+If the domain on which `exit` is called has been disposed, `exit` will return
+without exiting the domain.
+
 ### domain.dispose()
 
 The dispose method destroys a domain, and makes a best effort attempt to