dgram `socket.send()` documentation needs clarification

[Trott]

In the version of the dgram doc that is current as of this writing, the first argument (buf) is described initially as:

Buffer object, string, or an array of either. Message to be sent.

However, it is subsequently described as a Buffer object only:

The buf argument is a [Buffer] object containing the message. The offset
and length specify the offset within the Buffer where the message begins
and the number of bytes in the message, respectively. With messages that
contain multi-byte characters, offset and length will be calculated with
respect to [byte length][] and not the character position.

Additionally, it is not clear what offset and length mean when the buf argument is an array. It's also not clear if the multi-byte caveat applies if buf is a string or only if buf is a Buffer object.

It may be worth changing the name from buf to msg or something like that.

/cc @nodejs/documentation

[silverwind]

cc: @mcollina

[eljefedelrodeodeljefe]

That is a very good idea, if this is working correctly.

[mcollina]

Thanks @silverwind! And thanks for reviewing @Trott!

@eljefedelrodeodeljefe what do you refer to? #4374 should work as expected yes.

Just to clarify:

1. offset and len means nothing if an array is passed.
2. you can pass strings in the array form, which will be converted to Buffer with 'utf8' encoding. (this was never specified even in the original docs).

It may be worth changing the name from buf to msg or something like that.

yes, agreed.

I will send a PR to update the docs and resolve this.

[eljefedelrodeodeljefe]

@mcollina nothing special. Just haven't tested passing non-Buffer primitives.

[mcollina]

@eljefedelrodeodeljefe please do :).

[mcollina]

PR sent #5130