doc: improve docs for net.connect, net.createConnection, net.Socket #11700

joyeecheung · 2017-03-05T20:44:36Z

This is a follow up of #11636.

Nest the overloaded arguments
Added type annotations
alias net.connect to net.createConnection (now in the code they are ===)
Add links to man pages for reference
General improvements to wording and explanation

Checklist

make -j4 test (UNIX), or vcbuild test (Windows) passes
documentation is changed or added
commit message follows commit guidelines

Affected core subsystem(s)

doc, net

sam-github · 2017-03-06T17:06:12Z

doc/api/net.md

-user and used as a client (with [`connect()`][]) or they can be created by Node.js
-and passed to the user through the `'connection'` event of a server.
+This class is an abstraction of a TCP socket, a UNIX domain socket, or
+a Windows named pipe. A `net.Socket` is also a [duplex stream][], so it


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)

sam-github · 2017-03-06T17:10:02Z

doc/api/net.md

+a Windows named pipe. A `net.Socket` is also a [duplex stream][], so it
+can be both readable and writable, and it is also a [`EventEmitter`][].
+
+A `net.Socket` can be created by the user and used as an abstraction


"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).

sam-github · 2017-03-06T17:11:22Z

doc/api/net.md

+of the client. For example, it is returned by [`net.createConnection()`][],
+so the user can use it to interact with the server.
+
+It can also be be created by Node.js and passed to the user as an abstraction


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

sam-github · 2017-03-06T17:12:38Z

doc/api/net.md

-`net.Socket` instances are [`EventEmitter`][] with the following events:
+* `options` {Object} Available options are:
+  * `fd`: {number | null} Defaults to `null`. If specified, wrap around an
+    existing socket with the given file descriptor.


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

sam-github · 2017-03-06T17:13:39Z

doc/api/net.md

+    existing socket with the given file descriptor.
+  * `allowHalfOpen` {boolean} Default to `false`. Indicates whether
+    half-opened TCP connections are allowed. See [`net.createServer()`][]
+    and [`'end'`][] event for details.


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

sam-github · 2017-03-06T17:23:54Z

doc/api/net.md

-  - `hints`: [`dns.lookup()` hints][]. Defaults to `0`.
+* `port` {number} Required. Port the socket should connect to.
+* `host` {string} Host the socket should connect to. Defaults to `'localhost'`.
+* `localAddress` {string} Optional. Local address the socket should send


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

sam-github · 2017-03-06T17:24:22Z

doc/api/net.md

+* `host` {string} Host the socket should connect to. Defaults to `'localhost'`.
+* `localAddress` {string} Optional. Local address the socket should send
+  connections from.
+* `localPort` {number} Optional. Local port the socket should send connections


sam-github · 2017-03-06T17:25:48Z

doc/api/net.md

-
-`net.Socket` instances are [`EventEmitter`][] with the following events:
+* `options` {Object} Available options are:
+  * `fd`: {number | null} Defaults to `null`. If specified, wrap around an


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.

sam-github · 2017-03-06T17:28:19Z

doc/api/net.md


-Normally this method is not needed, as `net.createConnection` opens the
-socket. Use this only if you are implementing a custom Socket.
+* `path` {string} Required. Path the client should connect to.


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.

sam-github · 2017-03-06T17:30:57Z

doc/api/net.md


-## net.createConnection(options[, connectListener])
+This function is asynchronous. When the connection is established, a


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....

joyeecheung · 2017-03-07T08:00:31Z

@sam-github Thanks for the review! Addressed most comments, apart from #11700 (comment).

Added a section about IPC support and how to specify the paths (mostly moved from server.listen docs), and made other relevant APIs link to it.

joyeecheung · 2017-03-08T15:56:20Z

@sam-github Removed the man pages references...PTAL, thanks

sam-github

I like the way you have brought the IPC section out to a seperate section, looks great.

sam-github · 2017-03-08T16:38:26Z

doc/api/net.md

+### Identifying paths for IPC connections
+
+[`net.connect()`][], [`net.createConnection()`][], [`server.listen()`][] and
+[`socket.connect()`][] takes a `path` parameter to identify IPC endpoints.


sam-github · 2017-03-08T16:38:40Z

doc/api/net.md

+[`net.connect()`][], [`net.createConnection()`][], [`server.listen()`][] and
+[`socket.connect()`][] takes a `path` parameter to identify IPC endpoints.
+
+On UNIX, the local domain is usually known as the UNIX domain. The path is a


usually -> also

sam-github · 2017-03-08T16:44:45Z

doc/api/net.md

+*Note*: Unix named pipes (FIFOs) are not supported.
+
+On Windows, the local domain is implemented using a named pipe. The path *must*
+refer to an entry in `\\?\pipe\` or `\\.\pipe\`. Any characters are permitted,


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)

sam-github · 2017-03-08T16:47:52Z

doc/api/net.md

-socket (NOTE: Works only when `fd` is passed).
-About `allowHalfOpen`, refer to [`net.createServer()`][] and [`'end'`][] event.
+* `options` {Object} Available options are:
+  * `fd`: {number | null} If specified, wrap around an existing socket with


{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.

sam-github · 2017-03-08T16:49:31Z

doc/api/net.md

+
+It can also be be created by Node.js and passed to the user when a connection
+is received. For example, it is passed to the listeners of a
+[`'connection'`][] event fired on a [`net.Server`][], so the user can use


"fired" -> "emitted"

sam-github · 2017-03-08T16:51:55Z

doc/api/net.md

 [half-closed]: https://tools.ietf.org/html/rfc1122#section-4.2.2.13
+[IPC]: #net_ipc_support


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

sam-github · 2017-03-08T16:56:23Z

doc/api/net.md


 ```js
 const net = require('net');
 ```

+## IPC Support
+
+The `net` module supports IPC with named pipes on Windows, and domain sockets


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

sam-github · 2017-03-08T17:01:30Z

doc/api/net.md

+on file creation. It will be visible in the filesystem, and will *persist until
+unlinked*.
+
+*Note*: Unix named pipes (FIFOs) are not supported.


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.

sam-github · 2017-03-09T18:03:03Z

or maybe I should have waited before approving, but when the nits you thumbed up above are addressed, this LGTM

* Nest the overloaded signatures * Add references to system call manuals * Improve links

* Nest the overloaded signatures * Improve links

joyeecheung · 2017-03-09T23:50:26Z

Addressed comments and rebased.

CI: https://ci.nodejs.org/job/node-test-pull-request/6779/

* Add type annotations to the options * Improve the descriptions of net.Socket class

jasnell

LGTM with a nit

jasnell · 2017-03-10T04:51:11Z

doc/api/net.md


 ### socket.connecting
 <!-- YAML
 added: v6.1.0
 -->

-If `true` - [`socket.connect(options[, connectListener])`][`socket.connect(options, connectListener)`] was called and
+If `true` - [`socket.connect(options[, connectListener])`][`socket.connect(options)`] was called and


Please wrap at 80 chars :-)

joyeecheung · 2017-03-10T05:18:50Z

@jasnell Fixed 80-character wrap, thanks.

(Aside: the wording of socket.connecting can be improved...probably in another PR)

Going to land this tomorrow.

joyeecheung · 2017-03-11T02:50:12Z

Landed in df97727, thanks!

* Improve description of socket.connect, net.connect, net.createConnection * Nest the overloaded signatures * Alias net.connect to net.createConnection * Add type annotations to the options * Make a separate section to explain IPC support and how to specify the path parameter. * General improvements to wording and explanation PR-URL: #11700 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Sam Roberts <[email protected]>

italoacasas · 2017-03-13T15:51:24Z

@joyeecheung this is not landing clearly in v7.x, can backport?

* Improve description of socket.connect, net.connect, net.createConnection * Nest the overloaded signatures * Alias net.connect to net.createConnection * Add type annotations to the options * Make a separate section to explain IPC support and how to specify the path parameter. * General improvements to wording and explanation PR-URL: nodejs#11700 Reviewed-By: James M Snell <[email protected]> Reviewed-By: Sam Roberts <[email protected]>

gibfahn · 2017-06-17T22:01:47Z

Should this be backported to v6.x-staging? If yes please follow the guide and raise a backport PR, if no let me know or add the dont-land-on label.

nodejs-github-bot added doc Issues and PRs related to the documentations. net Issues and PRs related to the net subsystem. labels Mar 5, 2017

joyeecheung force-pushed the net-socket-doc branch from 8768384 to 3271f84 Compare March 5, 2017 20:51

sam-github suggested changes Mar 6, 2017

View reviewed changes

joyeecheung force-pushed the net-socket-doc branch from 3271f84 to 33cae98 Compare March 7, 2017 07:59

sam-github suggested changes Mar 8, 2017

View reviewed changes

sam-github approved these changes Mar 9, 2017

View reviewed changes

joyeecheung added 4 commits March 10, 2017 07:47

doc: add IPC support and s/local/IPC/

17278b8

doc: improve socket.connect description

47e9447

* Nest the overloaded signatures * Add references to system call manuals * Improve links

doc: alias net.connect to net.createConnection

5c4acdb

doc: improve net.createConnection description

27ec424

* Nest the overloaded signatures * Improve links

joyeecheung force-pushed the net-socket-doc branch from 499a773 to 834b9ea Compare March 9, 2017 23:48

doc: improve net.Socket class description

f10e2ba

* Add type annotations to the options * Improve the descriptions of net.Socket class

joyeecheung force-pushed the net-socket-doc branch 2 times, most recently from 2909de5 to 090607c Compare March 9, 2017 23:56

doc: move the explanation of path parameter

090607c

jasnell approved these changes Mar 10, 2017

View reviewed changes

joyeecheung force-pushed the net-socket-doc branch 2 times, most recently from 8c948d8 to ce0c668 Compare March 10, 2017 05:21

fix wrap

ce0c668

joyeecheung closed this Mar 11, 2017

italoacasas added the dont-land-on-v7.x label Mar 21, 2017

jasnell mentioned this pull request Apr 4, 2017

8.0.0 Release Proposal #12220

Closed

gibfahn mentioned this pull request Jun 15, 2017

Auditing for 6.11.1 nodejs/Release#230

Closed

3 tasks

gibfahn added the backport-requested-v6.x label Jun 17, 2017

joyeecheung self-assigned this Oct 17, 2017

joyeecheung added dont-land-on-v6.x and removed backport-requested-v6.x labels Nov 1, 2017

joyeecheung removed their assignment Nov 1, 2017


		## net.createConnection(options[, connectListener])
		This function is asynchronous. When the connection is established, a

		[half-closed]: https://tools.ietf.org/html/rfc1122#section-4.2.2.13
		[IPC]: #net_ipc_support

doc: improve docs for net.connect, net.createConnection, net.Socket #11700

doc: improve docs for net.connect, net.createConnection, net.Socket #11700

Conversation

joyeecheung commented Mar 5, 2017

Checklist

Affected core subsystem(s)

Choose a reason for hiding this comment

joyeecheung Mar 7, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

joyeecheung Mar 7, 2017 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

joyeecheung commented Mar 7, 2017 • edited Loading

joyeecheung commented Mar 8, 2017 • edited Loading

sam-github left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sam-github commented Mar 9, 2017

joyeecheung commented Mar 9, 2017

jasnell left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

joyeecheung commented Mar 10, 2017

joyeecheung commented Mar 11, 2017

italoacasas commented Mar 13, 2017

gibfahn commented Jun 17, 2017

joyeecheung Mar 7, 2017 •

edited

Loading

joyeecheung Mar 7, 2017 •

edited

Loading

joyeecheung commented Mar 7, 2017 •

edited

Loading

joyeecheung commented Mar 8, 2017 •

edited

Loading