doc: clarify lifecycle of domain sockets

In UNIX, the domain sockets once created persists until unlinked.
Clarify which ones are persisted and which ones are cleared manually.

In Windows, named pipes are cleared based on reference count,
implemented by the underlying system. Disambiguate this from
Garbage collection of the Node.js runtime.

Refs: https://github.com/nodejs/help/issues/1080

PR-URL: https://github.com/nodejs/node/pull/19471
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>

1 files changed, 16 insertions, 7 deletions

diff --git a/doc/api/net.md b/doc/api/net.md
index 4e76878d6e..c3192c84c8 100644
--- a/doc/api/net.md
+++ b/doc/api/net.md
@@ -26,20 +26,29 @@ sockets on other operating systems.
 [`socket.connect()`][] take a `path` parameter to identify IPC endpoints.
 
 On UNIX, the local domain is also known as the UNIX domain. The path is a
-filesystem path name. It gets truncated to `sizeof(sockaddr_un.sun_path) - 1`,
+filesystem pathname. It gets truncated to `sizeof(sockaddr_un.sun_path) - 1`,
 which varies on different operating system between 91 and 107 bytes.
 The typical values are 107 on Linux and 103 on macOS. The path is
 subject to the same naming conventions and permissions checks as would be done
-on file creation. It will be visible in the filesystem, and will *persist until
-unlinked*.
+on file creation. If the UNIX domain socket (that is visible as a file system
+path) is created and used in conjunction with one of Node.js' API abstractions
+such as [`net.createServer()`][], it will be unlinked as part of
+[`server.close()`][]. On the other hand, if it is created and used outside of
+these abstractions, the user will need to manually remove it. The same applies
+when the path was created by a Node.js API but the program crashes abruptly.
+In short, a UNIX domain socket once successfully created will be visible in the
+filesystem, and will persist until unlinked.
 
 On Windows, the local domain is implemented using a named pipe. The path *must*
 refer to an entry in `\\?\pipe\` or `\\.\pipe\`. Any characters are permitted,
 but the latter may do some processing of pipe names, such as resolving `..`
-sequences. Despite appearances, the pipe name space is flat. Pipes will *not
-persist*, they are removed when the last reference to them is closed. Do not
-forget JavaScript string escaping requires paths to be specified with
-double-backslashes, such as:
+sequences. Despite how it might look, the pipe namespace is flat. Pipes will
+*not persist*. They are removed when the last reference to them is closed.
+Unlike UNIX domain sockets, Windows will close and remove the pipe when the
+owning process exits.
+
+JavaScript string escaping requires paths to be specified with extra backslash
+escaping such as:
 
 ```js
 net.createServer().listen(