1berry/nodejs
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

doc: fix nits in dgram.md

Browse Source 
* 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>
This commit is contained in:
Vse Mozhet Byt 2019-09-29 16:53:43 +03:00 committed by Rich Trott
parent 7ec558cb24
commit ddcd2359f4
1 changed files with 13 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

41
doc/api/dgram.md
View File

@ -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