doc: improve server.listen() random port

phillipj · cjihrig · commit 7fa4be0f87d9 · 2016-08-10T12:48:31.000-04:00
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: #7976 Reviewed-By: James M Snell <jasnell@gmail.com> Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
diff --git a/doc/api/http.md b/doc/api/http.md
@@ -691,15 +691,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
@@ -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
