consider: a abstraction of a TCP or local streaming socket (local uses named pipes on Windows, and UNIX domain sockets otherwise) ... this long list of underlying technologies seemed random to you at first, I think it will confuse others, and it would be good to emphasize the OS mechanism being abstracted is "local streaming IPC", it just happens to have different names on UNIX and Windows (the Windows O/S devs weren't about to call a core IPC mechanism "unix" I guess ;-).

I have considered using the term IPC but remembered people are using net abstractions over Windows named pipes for RPC as well? (I think I've seem issues about access permissions before, couldn't find the link).

So maybe: a abstraction of a TCP or streaming socket (uses named pipes on Windows, and UNIX domain sockets otherwise) (loses the local part)?

Er, wait, I think IPC still works because technically the name IPC doesn't imply it's local, it can be remote. s/streaming socket/streaming IPC/?

I've never seen anything that suggests that windows named pipes can be used between machines. And IPC doesn't have an exact definition, its like the word "process" itself, but it does usually imply same-host. Anyhow, I'm ok with any reasonable phrase, that we define and then use instead of writing out "named pipes on Windows and UNIX domain sockets on non-Windows" over and over.... @piscisaureus can named pipes be used between hosts?

FWIW, the MSDN says:

Named pipes can be used to provide communication between processes on the same computer or between processes on different computers across a network. If the server service is running, all named pipes are accessible remotely. If you intend to use a named pipe locally only, deny access to NT AUTHORITY\NETWORK or switch to local RPC.

I am not sure if Node.js actually supports this, but looks like the remote access is configured outside the application?
(er, nevermind, just saw your comment below this :D)

"used as an abstraction of the client" is a bit convoluted in my opinion, consider: "used directly to connect to a server". Almost all programming objects are in some sense "abstractions" (a url.URL is an abstraction of a "URL", a js-String is an abstraction of a "sequence of characters", etc., but its not how we usually describe them).

consider: "passed to the user when a connection is received"

otherwise ... ? If unspecified, the fd/socket will be created should be stated.

and the end event for details <--- need a "the"

"should connect from" (you don't really "send" connections)

ditto

general comment: there is a fairly random mix of style wrt. where the default is mentioned. sometines the default is first thing mentioned (here), sometimes it is the last thing (net.connect). I think it makes more sense to describe what an option does before describing its default.

+1 to describe the meaning before describing default. Also some docs use "Defaults to", some use "Default to". Not sure if we need to use present tense in the docs if a sentence starts this way? (This is a bit inconsistent in almost every API docs I've ever seen, not just Node.js..)

(random idea: it would be great if we have some structural way to describe the default, and let the doc tools generate something with different styles).

"Default to X" is ungrammatical, IMO. "Defaults to X" and "Default is X" both sound OK to me. Tooling would be good, too! Lots of work, though.

I think "Required." is unnecessary, its clearly not optional in the syntax above. There would be an awful lot of "Required." in our docs if we put that as the first word sentence for every mandatory positional parameter, which we don't.

This function is asynchronous.

I think this is misleading. The connection object is returned synchronously, but the establishment of the connection is asynchronous. Better would be something like:

Creates a socket object and initiates a connection. When the connection is established....

"take"

usually -> also

I thought if you listen on a path like 'path' it becomes \\?\pipe\path, not true?

There will be an EACCESS if the path is not prepended with that..see nodejs/node-v0.x-archive#2797 (comment)

{number} is sufficient, we don't call out undefined/null as independent types for unspecified options in our docs, not anywhere I can recall seeing. You don't do on the 3 other options that default to null just below, for example.

"fired" -> "emitted"

out of order, use default/ASCII/"C" locale sorting

"UNIX domain sockets", they are never called "domain sockets"! http://man7.org/linux/man-pages/man7/unix.7.html

This makes it sound like its a missing feature, when actually its an entirely diffferent IPC pattern that doesn't map to duplex streams, or to client/server communication patterns. Also, I expect that they are supported by node... using the fs API. If you are going to mention them here, I think you should mention something like "FIFOs on Unix are sometimes called "named pipes", but despite the similarity in name to Windows named pipes, they function completely differently, and aren't supported or relevant to the net API.". I think this is getting off track, though. The only people who would read this section and think "wait, what about UNIX named pipes?" are people who already know that there are UNIX named pipes... and those people already know that a FIFO is not representable as a bi-directional stream (IMO). I'm not wondering about unix pipes, socketpairs, or message queues when I read the net docs, either.

Yes it does look stranger if pulled out to here, where the context of net being about bidirectional streams is clearer. This can be removed.