doc: correct and complete dgram's Socket.bind docs

`port` was listed as required, but as described in the following
paragraphs, it's actually not.

Also, note that setting `port` to `0` will also cause the OS to assign a
a random port and sync up the docs of both forms.

PR-URL: https://github.com/nodejs/node/pull/11025
Reviewed-By: Sam Roberts <vieuxtech@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>

1 files changed, 26 insertions, 14 deletions

diff --git a/doc/api/dgram.md b/doc/api/dgram.md
index c059b6dc2ba..65a89913ba1 100644
--- a/doc/api/dgram.md
+++ b/doc/api/dgram.md
@@ -112,12 +112,13 @@ added: v0.1.99
 * `callback` {Function} with no parameters, Optional. Called when
   binding is complete.
 
-For UDP sockets, causes the `dgram.Socket` to listen for datagram messages on a
-named `port` and optional `address`. If `port` is not specified, the operating
-system will attempt to bind to a random port. If `address` is not specified,
-the operating system will attempt to listen on all addresses.  Once binding is
-complete, a `'listening'` event is emitted and the optional `callback` function
-is called.
+For UDP sockets, causes the `dgram.Socket` to listen for datagram
+messages on a named `port` and optional `address`. If `port` is not
+specified or is `0`, the operating system will attempt to bind to a
+random port. If `address` is not specified, the operating system will
+attempt to listen on all addresses.  Once binding is complete, a
+`'listening'` event is emitted and the optional `callback` function is
+called.
 
 Note that specifying both a `'listening'` event listener and passing a
 `callback` to the `socket.bind()` method is not harmful but not very
@@ -159,18 +160,23 @@ added: v0.11.14
 -->
 
 * `options` {Object} - Required. Supports the following properties:
-  * `port` {Number} - Required.
+  * `port` {Number} - Optional.
   * `address` {String} - Optional.
   * `exclusive` {Boolean} - Optional.
 * `callback` {Function} - Optional.
 
-For UDP sockets, causes the `dgram.Socket` to listen for datagram messages on a
-named `port` and optional `address` that are passed as properties of an
-`options` object passed as the first argument. If `port` is not specified, the
-operating system will attempt to bind to a random port. If `address` is not
-specified, the operating system will attempt to listen on all addresses.  Once
-binding is complete, a `'listening'` event is emitted and the optional
-`callback` function is called.
+For UDP sockets, causes the `dgram.Socket` to listen for datagram
+messages on a named `port` and optional `address` that are passed as
+properties of an `options` object passed as the first argument. If
+`port` is not specified or is `0`, the operating system will attempt
+to bind to a random port. If `address` is not specified, the operating
+system will attempt to listen on all addresses.  Once binding is
+complete, a `'listening'` event is emitted and the optional `callback`
+function is called.
+
+Note that specifying both a `'listening'` event listener and passing a
+`callback` to the `socket.bind()` method is not harmful but not very
+useful.
 
 The `options` object may contain an additional `exclusive` property that is
 use when using `dgram.Socket` objects with the [`cluster`] module. When
@@ -179,6 +185,12 @@ underlying socket handle allowing connection handling duties to be shared.
 When `exclusive` is `true`, however, the handle is not shared and attempted
 port sharing results in an error.
 
+A bound datagram socket keeps the Node.js process running to receive
+datagram messages.
+
+If binding fails, an `'error'` event is generated. In rare case (e.g.
+attempting to bind with a closed socket), an [`Error`][] may be thrown.
+
 An example socket listening on an exclusive port is shown below.
 
 ```js