doc: reword ambigous docs for socket.setNoDelay

[Xerkus]

Checklist

• documentation is changed or added
• commit message follows commit guidelines

Affected core subsystem(s)

doc

Description of change

Reworded description of socket.setNoDelay to make it clear that function parameter defaults to true and not the noDelay option itself.
See nodejs/node-v0.x-archive#8929

[ChALkeR]

This breaks the links, I presume.

The following line should also be changed:

doc/api/http.md:1524:[`socket.setNoDelay()`]: net.html#net_socket_setnodelay_nodelay

[ChALkeR]

That said, I'm not sure if it really makes sense to rename the argument to enable.

Thoughs?

[Xerkus]

it is too ambiguous otherwise and parameter name in code is enable: https://github.com/nodejs/node/blob/master/lib/net.js#L337

[sam-github]

This doesn't help, we used to have two concepts, "no delay" and "true/false", and we could tell that "nodelay" (the param name and method name) could be set to true.

Now, you enable (something?) and when something is enabled, "no delay" is... what? true? false? So I have to map enable to true, and true to "no delay" being on, which is a hop too many.

[sam-github]

or maybe when "enable" is false, nagle is disabled... so "no delay" is true? In which case, the meaning of true/false to this function would be inverted, so that's an API change, and we would never do it.

[jasnell]

Another way this could be reworded is:

By default, TCP connections use the Nagle algorithm to buffer data before
sending. Calling `socket.setNoDelay(true)` disables such buffering so that
data is sent each time `socket.write()` is called.

The `enable` argument defaults to `true`.

[silverwind]

Also to note, the assumption By default TCP connections use the Nagle algorithm is not entirely correct. Node.js currently does not explicitely set this socket option, it just happens to be the default on Linux, but not on Windows for example. #906 shall eventually resolve this, but I haven't gotten around to it yet.

[jasnell]

Still want to pursue this?

[Xerkus]

I am not a native speaker, and there were objections to the change. I am not sure if i was wrong here.

[jasnell]

@Xerkus ... no problem. I'll keep it open and will take a look to see what else we can do here.

[fhinkel]

@silverwind and @sam-github can you make suggestions how you'd rather have the documentation worded so we can change it and land it? Thanks.

[sam-github]

We did make suggestions, didn't we? EDIT: yes, there were specific suggestions made, including text by @jasnell, that the OP has not followed up on.

[jasnell]

Closing due to lack of forward progress on this. It's likely still a change that should be made tho.

[chrisbutler]

please please please can we fix this madness? i'd be happy to take a stab at it