From 0c5981b226350730126731bc0d546009570805e1 Mon Sep 17 00:00:00 2001 From: Ben Noordhuis Date: Tue, 29 Oct 2013 10:31:14 +0100 Subject: [PATCH] doc: dgram: reword dgram.Socket#send() docs Make it clear that the address argument is not really optional and fix some Engrish and long lines while we're here. Fixes #6433. --- doc/api/dgram.markdown | 30 +++++++++++++++++------------- 1 file changed, 17 insertions(+), 13 deletions(-) diff --git a/doc/api/dgram.markdown b/doc/api/dgram.markdown index 6e8f73fe49a..2ff280679a4 100644 --- a/doc/api/dgram.markdown +++ b/doc/api/dgram.markdown @@ -72,21 +72,25 @@ Emitted when an error occurs. * `buf` Buffer object. Message to be sent * `offset` Integer. Offset in the buffer where the message starts. * `length` Integer. Number of bytes in the message. -* `port` Integer. destination port -* `address` String. destination IP -* `callback` Function. Callback when message is done being delivered. - Optional. +* `port` Integer. Destination port. +* `address` String. Destination hostname or IP address. +* `callback` Function. Called when the message has been sent. Optional. -For UDP sockets, the destination port and IP address must be specified. A string -may be supplied for the `address` parameter, and it will be resolved with DNS. An -optional callback may be specified to detect any DNS errors and when `buf` may be -re-used. Note that DNS lookups will delay the time that a send takes place, at -least until the next tick. The only way to know for sure that a send has taken place -is to use the callback. +For UDP sockets, the destination port and address must be specified. A string +may be supplied for the `address` parameter, and it will be resolved with DNS. -If the socket has not been previously bound with a call to `bind`, it's -assigned a random port number and bound to the "all interfaces" address -(0.0.0.0 for `udp4` sockets, ::0 for `udp6` sockets). +If the address is omitted or is an empty string, `'0.0.0.0'` or `'::0'` is used +instead. Depending on the network configuration, those defaults may or may not +work; it's best to be explicit about the destination address. + +If the socket has not been previously bound with a call to `bind`, it gets +assigned a random port number and is bound to the "all interfaces" address +(`'0.0.0.0'` for `udp4` sockets, `'::0'` for `udp6` sockets.) + +An optional callback may be specified to detect DNS errors or for determining +when it's safe to reuse the `buf` object. Note that DNS lookups delay the time +to send for at least one tick. The only way to know for sure that the datagram +has been sent is by using a callback. Example of sending a UDP packet to a random port on `localhost`;