Skip to content

Commit

Permalink
doc: fix nits in dgram.md
Browse files Browse the repository at this point in the history
* Make a section with a history remark a YAML section
  of the relevant method.
  Refs: #29761 (comment)
* 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: #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>
  • Loading branch information
vsemozhetbyt authored and Trott committed Oct 1, 2019
1 parent 7ec558c commit ddcd235
Showing 1 changed file with 13 additions and 28 deletions.
41 changes: 13 additions & 28 deletions doc/api/dgram.md
Original file line number Diff line number Diff line change
Expand Up @@ -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}
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand All @@ -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])
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down

0 comments on commit ddcd235

Please sign in to comment.