From 29139bff65571f7f294e0b2b992437144b160bf4 Mon Sep 17 00:00:00 2001
From: Phillip Johnsen <johphi@gmail.com>
Date: Mon, 8 Aug 2016 23:31:27 +0200
Subject: [PATCH] doc: improve server.listen() random port

Minor rewording related to making a server listen to a random port,
and added how to retrieve which port was randomly chosen by the OS.

Also changed documented `server.listen()` signature as it does in fact
not require `port` to be provided.

PR-URL: https://github.com/nodejs/node/pull/8025
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
---
 doc/api/http.md |  8 +++++---
 doc/api/net.md  | 17 +++++++++--------
 2 files changed, 14 insertions(+), 11 deletions(-)

diff --git a/doc/api/http.md b/doc/api/http.md
index 01e4244e2a8d68..a01408c321d21d 100644
--- a/doc/api/http.md
+++ b/doc/api/http.md
@@ -640,15 +640,17 @@ Start a UNIX socket server listening for connections on the given `path`.
 This function is asynchronous. `callback` will be added as a listener for the
 `'listening'` event.  See also [`net.Server.listen(path)`][].
 
-### server.listen(port[, hostname][, backlog][, callback])
+### server.listen([port][, hostname][, backlog][, callback])
 <!-- YAML
 added: v0.1.90
 -->
 
 Begin accepting connections on the specified `port` and `hostname`. If the
 `hostname` is omitted, the server will accept connections on any IPv6 address
-(`::`) when IPv6 is available, or any IPv4 address (`0.0.0.0`) otherwise. Use a
-port value of `0` to have the operating system assign an available port.
+(`::`) when IPv6 is available, or any IPv4 address (`0.0.0.0`) otherwise.
+Omit the port argument, or use a port value of `0`, to have the operating system
+assign a random port, which can be retrieved by using `server.address().port`
+after the `'listening'` event has been emitted.
 
 To listen to a unix socket, supply a filename instead of port and hostname.
 
diff --git a/doc/api/net.md b/doc/api/net.md
index cc93231c5eb713..0e1099227d0b3d 100644
--- a/doc/api/net.md
+++ b/doc/api/net.md
@@ -73,8 +73,7 @@ var server = net.createServer((socket) => {
 
 // grab a random port.
 server.listen(() => {
-  address = server.address();
-  console.log('opened server on %j', address);
+  console.log('opened server on', server.address());
 });
 ```
 
@@ -140,7 +139,7 @@ The last parameter `callback` will be added as a listener for the
 [`'listening'`][] event.
 
 The parameter `backlog` behaves the same as in
-[`server.listen(port[, hostname][, backlog][, callback])`][`server.listen(port, host, backlog, callback)`].
+[`server.listen([port][, hostname][, backlog][, callback])`][`server.listen(port, host, backlog, callback)`].
 
 ### server.listen(options[, callback])
 <!-- YAML
@@ -157,7 +156,7 @@ added: v0.11.14
 
 The `port`, `host`, and `backlog` properties of `options`, as well as the
 optional callback function, behave as they do on a call to
-[`server.listen(port[, hostname][, backlog][, callback])`][`server.listen(port, host, backlog, callback)`].
+[`server.listen([port][, hostname][, backlog][, callback])`][`server.listen(port, host, backlog, callback)`].
 Alternatively, the `path` option can be used to specify a UNIX socket.
 
 If `exclusive` is `false` (default), then cluster workers will use the same
@@ -209,17 +208,19 @@ double-backslashes, such as:
         path.join('\\\\?\\pipe', process.cwd(), 'myctl'))
 
 The parameter `backlog` behaves the same as in
-[`server.listen(port[, hostname][, backlog][, callback])`][`server.listen(port, host, backlog, callback)`].
+[`server.listen([port][, hostname][, backlog][, callback])`][`server.listen(port, host, backlog, callback)`].
 
-### server.listen(port[, hostname][, backlog][, callback])
+### server.listen([port][, hostname][, backlog][, callback])
 <!-- YAML
 added: v0.1.90
 -->
 
 Begin accepting connections on the specified `port` and `hostname`. If the
 `hostname` is omitted, the server will accept connections on any IPv6 address
-(`::`) when IPv6 is available, or any IPv4 address (`0.0.0.0`) otherwise. Use a
-port value of `0` to have the operating system assign an available port.
+(`::`) when IPv6 is available, or any IPv4 address (`0.0.0.0`) otherwise.
+Omit the port argument, or use a port value of `0`, to have the operating system
+assign a random port, which can be retrieved by using `server.address().port`
+after the `'listening'` event has been emitted.
 
 Backlog is the maximum length of the queue of pending connections.
 The actual length will be determined by the OS through sysctl settings such as