Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: fix inconsistent documentation of server.listen() #16020

Closed
wants to merge 4 commits into from
Closed

doc: fix inconsistent documentation of server.listen() #16020

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
d5e1492
doc: fix inconsistent documentation of server.listen()
mgjm Oct 6, 2017
6877211
doc: fixed order in https module
mgjm Oct 6, 2017
4f7cf5f
doc: fix inconsistent documentation of server.listen()
mgjm Oct 14, 2017
f9fbfc6
doc: change server.close in https
mgjm Oct 14, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
81 changes: 3 additions & 78 deletions doc/api/http.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -841,85 +841,9 @@ added: v0.1.90

Stops the server from accepting new connections. See [`net.Server.close()`][].

### server.listen(handle[, callback])
<!-- YAML
added: v0.5.10
-->

* `handle` {Object}
* `callback` {Function}

The `handle` object can be set to either a server or socket (anything
with an underlying `_handle` member), or a `{fd: <n>}` object.

This will cause the server to accept connections on the specified
handle, but it is presumed that the file descriptor or handle has
already been bound to a port or domain socket.

Listening on a file descriptor is not supported on Windows.

This function is asynchronous. `callback` will be added as a listener for the
[`'listening'`][] event. See also [`net.Server.listen()`][].

Returns `server`.

*Note*: The `server.listen()` method can be called again if and only if there was an error
during the first `server.listen()` call or `server.close()` has been called.
Otherwise, an `ERR_SERVER_ALREADY_LISTEN` error will be thrown.

### server.listen(path[, callback])
<!-- YAML
added: v0.1.90
-->

* `path` {string}
* `callback` {Function}

Start a UNIX socket server listening for connections on the given `path`.

This function is asynchronous. `callback` will be added as a listener for the
[`'listening'`][] event. See also [`net.Server.listen(path)`][].

*Note*: The `server.listen()` method can be called again if and only if there was an error
during the first `server.listen()` call or `server.close()` has been called.
Otherwise, an `ERR_SERVER_ALREADY_LISTEN` error will be thrown.

### server.listen([port][, hostname][, backlog][, callback])
<!-- YAML
added: v0.1.90
-->

* `port` {number}
* `hostname` {string}
* `backlog` {number}
* `callback` {Function}

Begin accepting connections on the specified `port` and `hostname`. If the
`hostname` is omitted, the server will accept connections on the
[unspecified IPv6 address][] (`::`) when IPv6 is available, or the
[unspecified IPv4 address][] (`0.0.0.0`) otherwise.

*Note*: In most operating systems, listening to the
[unspecified IPv6 address][] (`::`) may cause the `net.Server` to also listen on
the [unspecified IPv4 address][] (`0.0.0.0`).

Omit the port argument, or use a port value of `0`, to have the operating system
assign a random port, which can be retrieved by using `server.address().port`
after the `'listening'` event has been emitted.

To listen to a unix socket, supply a filename instead of port and hostname.

`backlog` is the maximum length of the queue of pending connections.
The actual length will be determined by the OS through sysctl settings such as
`tcp_max_syn_backlog` and `somaxconn` on linux. The default value of this
parameter is 511 (not 512).

This function is asynchronous. `callback` will be added as a listener for the
[`'listening'`][] event. See also [`net.Server.listen(port)`][].
### server.listen()

*Note*: The `server.listen()` method can be called again if and only if there was an error
during the first `server.listen()` call or `server.close()` has been called.
Otherwise, an `ERR_SERVER_ALREADY_LISTEN` error will be thrown.
Start a server listening for connections. This method is identical to [`server.listen()`][] from [`net.Server`][].
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wouldn't put this as

This method is identical to [`server.listen()`][] from [`net.Server`][].

because it starts a HTTP server, not a bare TCP/IPC server. IMO a better way to put this would be something like:

Starts the HTTP server listening for connections.
This method has the same signatures as [`server.listen()`][] from [`net.Server`][].

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actually the two methods are equal net.Server.prototype.listen === http.Server.prototype.listen. So a compromise would be:

Starts the HTTP server listening for connections.
This method is identical to [`server.listen()`][] from [`net.Server`][].


### server.listening
<!-- YAML
Expand Down Expand Up @@ -1963,6 +1887,7 @@ const req = http.request(options, (res) => {
[`net.Server.listen(path)`]: net.html#net_server_listen_path_backlog_callback
[`net.Server.listen(port)`]: net.html#net_server_listen_port_host_backlog_callback
[`net.Server`]: net.html#net_class_net_server
[`server.listen()`]: net.html#net_server_listen
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All of these should be in the sorted order.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am not certain if there is a lint rule for things like this but this would be pretty neat!

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would like to address this in another PR and write some automation / linting to check for the order of the documented methods as well as the order of the links

[`net.Socket`]: net.html#net_class_net_socket
[`net.createConnection()`]: net.html#net_net_createconnection_options_connectlistener
[`removeHeader(name)`]: #http_request_removeheader_name
Expand Down
38 changes: 14 additions & 24 deletions doc/api/https.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,18 @@ added: v0.3.4
This class is a subclass of `tls.Server` and emits events same as
[`http.Server`][]. See [`http.Server`][] for more information.

### server.close([callback])
<!-- YAML
added: v0.1.90
-->
- `callback` {Function}

See [`http.close()`][] for details.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

http.close() is a little bit ambiguous. Maybe

See [`server.close()`][`http.close()`] from the HTTP module for details.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I only moved the description of http.close() to another location. But it would be a nice change to make the description better.


### server.listen()

Start a server listening for connections. This method is identical to [`server.listen()`][] from [`net.Server`][].

### server.setTimeout([msecs][, callback])
<!-- YAML
added: v0.11.2
Expand Down Expand Up @@ -90,30 +102,6 @@ https.createServer(options, (req, res) => {
}).listen(8000);
```

### server.close([callback])
<!-- YAML
added: v0.1.90
-->
- `callback` {Function}

See [`http.close()`][] for details.

### server.listen(handle[, callback])
- `handle` {Object}
- `callback` {Function}

### server.listen(path[, callback])
- `path` {string}
- `callback` {Function}

### server.listen([port][, host][, backlog][, callback])
- `port` {number}
- `hostname` {string}
- `backlog` {number}
- `callback` {Function}

See [`http.listen()`][] for details.

## https.get(options[, callback])
<!-- YAML
added: v0.3.6
Expand Down Expand Up @@ -261,6 +249,8 @@ const req = https.request(options, (res) => {

[`Agent`]: #https_class_https_agent
[`URL`]: url.html#url_the_whatwg_url_api
[`net.Server`]: net.html#net_class_net_server
[`server.listen()`]: net.html#net_server_listen
[`http.Agent`]: http.html#http_class_http_agent
[`http.Server#keepAliveTimeout`]: http.html#http_server_keepalivetimeout
[`http.Server#setTimeout()`]: http.html#http_server_settimeout_msecs_callback
Expand Down
23 changes: 3 additions & 20 deletions doc/api/tls.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -408,27 +408,9 @@ added: v3.0.0
Returns a `Buffer` instance holding the keys currently used for
encryption/decryption of the [TLS Session Tickets][]

### server.listen(port[, hostname][, callback])
<!-- YAML
added: v0.3.2
-->

* `port` {number} The TCP/IP port on which to begin listening for connections.
A value of `0` (zero) will assign a random port.
* `hostname` {string} The hostname, IPv4, or IPv6 address on which to begin
listening for connections. If `undefined`, the server will accept connections
on any IPv6 address (`::`) when IPv6 is available, or any IPv4 address
(`0.0.0.0`) otherwise.
* `callback` {Function} A callback function to be invoked when the server has
begun listening on the `port` and `hostname`.

The `server.listen()` methods instructs the server to begin accepting
connections on the specified `port` and `hostname`.

This function operates asynchronously. If the `callback` is given, it will be
called when the server has started listening.
### server.listen()

See [`net.Server`][] for more information.
Start a server listening for connections. This method is identical to [`server.listen()`][] from [`net.Server`][].

### server.setTicketKeys(keys)
<!-- YAML
Expand Down Expand Up @@ -1290,6 +1272,7 @@ where `secure_socket` has the same API as `pair.cleartext`.
[`crypto.getCurves()`]: crypto.html#crypto_crypto_getcurves
[`net.Server.address()`]: net.html#net_server_address
[`net.Server`]: net.html#net_class_net_server
[`server.listen()`]: net.html#net_server_listen
[`net.Socket`]: net.html#net_class_net_socket
[`server.getConnections()`]: net.html#net_server_getconnections_callback
[`tls.DEFAULT_ECDH_CURVE`]: #tls_tls_default_ecdh_curve
Expand Down