From 401f3e723502bfc2181c5d4cccd6444d7103fc55 Mon Sep 17 00:00:00 2001 From: Vse Mozhet Byt Date: Sun, 29 Sep 2019 16:53:43 +0300 Subject: [PATCH] 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 Reviewed-By: Rich Trott Reviewed-By: Luigi Pinca Reviewed-By: Trivikram Kamat Reviewed-By: Minwoo Jung Reviewed-By: Colin Ihrig Reviewed-By: James M Snell Reviewed-By: Ruben Bridgewater --- doc/api/dgram.md | 41 +++++++++++++---------------------------- 1 file changed, 13 insertions(+), 28 deletions(-) diff --git a/doc/api/dgram.md b/doc/api/dgram.md index ef8cc69b7d18e1..7d8684f7f6daa7 100644 --- a/doc/api/dgram.md +++ b/doc/api/dgram.md @@ -137,6 +137,11 @@ properties. ### socket.bind([port][, address][, callback]) * `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