doc: fix nits in dgram.md

* Make a section with a history remark a YAML section
  of the relevant method.
  Refs: https://github.com/nodejs/node/pull/29761#discussion_r329354848
* Make a bold line a real heading to be included in the TOC.
* Add formal return types.
* Reduce redundancy in a description.
* Unify link format.
* Fix ASCII sorting in bottom references.

PR-URL: https://github.com/nodejs/node/pull/29761
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>
Reviewed-By: Minwoo Jung <minwoo@nodesource.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>

1 files changed, 13 insertions, 28 deletions

diff --git a/doc/api/dgram.md b/doc/api/dgram.md
index ef8cc69b7d..7d8684f7f6 100644
--- a/doc/api/dgram.md
+++ b/doc/api/dgram.md
@@ -137,6 +137,11 @@ properties.
 ### socket.bind([port][, address][, callback])
 <!-- YAML
 added: v0.1.99
+changes:
+  - version: v0.10
+    description: The method was changed to an asynchronous execution model.
+                 Legacy code would need to be changed to pass a callback
+                 function to the method call.
 -->
 
 * `port` {integer}
@@ -216,7 +221,7 @@ Specifying both a `'listening'` event listener and passing a
 useful.
 
 The `options` object may contain an additional `exclusive` property that is
-used when using `dgram.Socket` objects with the [`cluster`] module. When
+used when using `dgram.Socket` objects with the [`cluster`][] module. When
 `exclusive` is set to `false` (the default), cluster workers will use the same
 underlying socket handle allowing connection handling duties to be shared.
 When `exclusive` is `true`, however, the handle is not shared and attempted
@@ -311,6 +316,8 @@ added: v8.7.0
 added: v0.9.1
 -->
 
+* Returns: {dgram.Socket}
+
 By default, binding a socket will cause it to block the Node.js process from
 exiting as long as the socket is open. The `socket.unref()` method can be used
 to exclude the socket from the reference counting that keeps the Node.js
@@ -444,7 +451,7 @@ client.connect(41234, 'localhost', (err) => {
 });
 ```
 
-**A Note about UDP datagram size**
+#### Note about UDP datagram size
 
 The maximum size of an `IPv4/v6` datagram depends on the `MTU`
 (_Maximum Transmission Unit_) and on the `Payload Length` field size.
@@ -626,6 +633,8 @@ The default on most systems is 64 but can vary.
 added: v0.9.1
 -->
 
+* Returns: {dgram.Socket}
+
 By default, binding a socket will cause it to block the Node.js process from
 exiting as long as the socket is open. The `socket.unref()` method can be used
 to exclude the socket from the reference counting that keeps the Node.js
@@ -637,27 +646,6 @@ Calling `socket.unref()` multiple times will have no addition effect.
 The `socket.unref()` method returns a reference to the socket so calls can be
 chained.
 
-### Change to asynchronous `socket.bind()` behavior
-
-As of Node.js v0.10, [`dgram.Socket#bind()`][] changed to an asynchronous
-execution model. Legacy code would use synchronous behavior:
-
-```js
-const s = dgram.createSocket('udp4');
-s.bind(1234);
-s.addMembership('224.0.0.114');
-```
-
-Such legacy code would need to be changed to pass a callback function to the
-[`dgram.Socket#bind()`][] function:
-
-```js
-const s = dgram.createSocket('udp4');
-s.bind(1234, () => {
-  s.addMembership('224.0.0.114');
-});
-```
-
 ## `dgram` module functions
 
 ### dgram.createSocket(options[, callback])
@@ -708,9 +696,7 @@ added: v0.1.99
 * `callback` {Function} - Attached as a listener to `'message'` events.
 * Returns: {dgram.Socket}
 
-Creates a `dgram.Socket` object of the specified `type`. The `type` argument
-can be either `'udp4'` or `'udp6'`. An optional `callback` function can be
-passed which is added as a listener for `'message'` events.
+Creates a `dgram.Socket` object of the specified `type`.
 
 Once the socket is created, calling [`socket.bind()`][] will instruct the
 socket to begin listening for datagram messages. When `address` and `port` are
@@ -720,14 +706,13 @@ and `udp6` sockets). The bound address and port can be retrieved using
 [`socket.address().address`][] and [`socket.address().port`][].
 
 [`'close'`]: #dgram_event_close
-[`Error`]: errors.html#errors_class_error
 [`ERR_SOCKET_DGRAM_IS_CONNECTED`]: errors.html#errors_err_socket_dgram_is_connected
 [`ERR_SOCKET_DGRAM_NOT_CONNECTED`]: errors.html#errors_err_socket_dgram_not_connected
+[`Error`]: errors.html#errors_class_error
 [`System Error`]: errors.html#errors_class_systemerror
 [`close()`]: #dgram_socket_close_callback
 [`cluster`]: cluster.html
 [`connect()`]: #dgram_socket_connect_port_address_callback
-[`dgram.Socket#bind()`]: #dgram_socket_bind_options_callback
 [`dgram.createSocket()`]: #dgram_dgram_createsocket_options_callback
 [`dns.lookup()`]: dns.html#dns_dns_lookup_hostname_options_callback
 [`socket.address().address`]: #dgram_socket_address