[doc] Add punctuation for readability (#2213)

README.md

@@ -11,8 +11,8 @@ Passes the quite extensive Autobahn test suite: [server][server-report],
 [client][client-report].
 
 **Note**: This module does not work in the browser. The client in the docs is a
-reference to a back end with the role of a client in the WebSocket
-communication. Browser clients must use the native
+reference to a backend with the role of a client in the WebSocket communication.
+Browser clients must use the native
 [`WebSocket`](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket)
 object. To make the same code work seamlessly on Node.js and the browser, you
 can use one of the many wrappers available on npm, like
@@ -87,7 +87,7 @@ npm install --save-optional utf-8-validate
 
 This contains a binary polyfill for [`buffer.isUtf8()`][].
 
-To force ws to not use utf-8-validate, use the
+To force ws not to use utf-8-validate, use the
 [`WS_NO_UTF_8_VALIDATE`](./doc/ws.md#ws_no_utf_8_validate) environment variable.
 
 ## API docs
@@ -146,7 +146,7 @@ const wss = new WebSocketServer({
 ```
 
 The client will only use the extension if it is supported and enabled on the
-server. To always disable the extension on the client set the
+server. To always disable the extension on the client, set the
 `perMessageDeflate` option to `false`.
 
 ```js
@@ -451,11 +451,11 @@ wss.on('connection', function connection(ws, req) {
 
 ### How to detect and close broken connections?
 
-Sometimes the link between the server and the client can be interrupted in a way
-that keeps both the server and the client unaware of the broken state of the
+Sometimes, the link between the server and the client can be interrupted in a
+way that keeps both the server and the client unaware of the broken state of the
 connection (e.g. when pulling the cord).
 
-In these cases ping messages can be used as a means to verify that the remote
+In these cases, ping messages can be used as a means to verify that the remote
 endpoint is still responsive.
 
 ```js
@@ -490,7 +490,7 @@ wss.on('close', function close() {
 Pong messages are automatically sent in response to ping messages as required by
 the spec.
 
-Just like the server example above your clients might as well lose connection
+Just like the server example above, your clients might as well lose connection
 without knowing it. You might want to add a ping listener on your clients to
 prevent that. A simple implementation would be:
 

SECURITY.md

@@ -12,21 +12,21 @@ blocked instantly.
 
 ## Exceptions
 
-If you do not receive an acknowledgement within the said time frame please give
+If you do not receive an acknowledgement within the said time frame, please give
 us the benefit of the doubt as it's possible that we haven't seen it yet. In
-this case please send us a message **without details** using one of the
+this case, please send us a message **without details** using one of the
 following methods:
 
 - Contact the lead developers of this project on their personal e-mails. You can
-  find the e-mails in the git logs, for example using the following command:
+  find the e-mails in the git logs, for example, using the following command:
   `git --no-pager show -s --format='%an <%ae>' <gitsha>` where `<gitsha>` is the
   SHA1 of their latest commit in the project.
 - Create a GitHub issue stating contact details and the severity of the issue.
 
-Once we have acknowledged receipt of your report and confirmed the bug ourselves
-we will work with you to fix the vulnerability and publicly acknowledge your
-responsible disclosure, if you wish. In addition to that we will create and
-publish a security advisory to
+Once we have acknowledged receipt of your report and confirmed the bug
+ourselves, we will work with you to fix the vulnerability and publicly
+acknowledge your responsible disclosure, if you wish. In addition to that, we
+will create and publish a security advisory to
 [GitHub Security Advisories](https://github.com/websockets/ws/security/advisories?state=published).
 
 ## History

doc/ws.md

@@ -103,7 +103,7 @@ This class represents a WebSocket server. It extends the `EventEmitter`.
 Create a new server instance. One and only one of `port`, `server` or `noServer`
 must be provided or an error is thrown. An HTTP server is automatically created,
 started, and used if `port` is set. To use an external HTTP/S server instead,
-specify only `server` or `noServer`. In this case the HTTP/S server must be
+specify only `server` or `noServer`. In this case, the HTTP/S server must be
 started manually. The "noServer" mode allows the WebSocket server to be
 completely detached from the HTTP/S server. This makes it possible, for example,
 to share a single HTTP/S server between multiple WebSocket servers.
@@ -112,8 +112,8 @@ to share a single HTTP/S server between multiple WebSocket servers.
 > authentication in the `'upgrade'` event of the HTTP server. See examples for
 > more details.
 
-If `verifyClient` is not set then the handshake is automatically accepted. If it
-has a single parameter then `ws` will invoke it with the following argument:
+If `verifyClient` is not set, then the handshake is automatically accepted. If
+it has a single parameter, then `ws` will invoke it with the following argument:
 
 - `info` {Object}
   - `origin` {String} The value in the Origin header indicated by the client.
@@ -124,19 +124,19 @@ has a single parameter then `ws` will invoke it with the following argument:
 The return value (`Boolean`) of the function determines whether or not to accept
 the handshake.
 
-If `verifyClient` has two parameters then `ws` will invoke it with the following
-arguments:
+If `verifyClient` has two parameters, then `ws` will invoke it with the
+following arguments:
 
 - `info` {Object} Same as above.
 - `cb` {Function} A callback that must be called by the user upon inspection of
   the `info` fields. Arguments in this callback are:
   - `result` {Boolean} Whether or not to accept the handshake.
-  - `code` {Number} When `result` is `false` this field determines the HTTP
+  - `code` {Number} When `result` is `false`, this field determines the HTTP
     error status code to be sent to the client.
-  - `name` {String} When `result` is `false` this field determines the HTTP
+  - `name` {String} When `result` is `false`, this field determines the HTTP
     reason phrase.
-  - `headers` {Object} When `result` is `false` this field determines additional
-    HTTP headers to be sent to the client. For example,
+  - `headers` {Object} When `result` is `false`, this field determines
+    additional HTTP headers to be sent to the client. For example,
     `{ 'Retry-After': 120 }`.
 
 `handleProtocols` takes two arguments:
@@ -146,15 +146,15 @@ arguments:
 - `request` {http.IncomingMessage} The client HTTP GET request.
 
 The returned value sets the value of the `Sec-WebSocket-Protocol` header in the
-HTTP 101 response. If returned value is `false` the header is not added in the
+HTTP 101 response. If returned value is `false`, the header is not added in the
 response.
 
-If `handleProtocols` is not set then the first of the client's requested
+If `handleProtocols` is not set, then the first of the client's requested
 subprotocols is used.
 
 `perMessageDeflate` can be used to control the behavior of [permessage-deflate
 extension][permessage-deflate]. The extension is disabled when `false` (default
-value). If an object is provided then that is extension parameters:
+value). If an object is provided, then that is extension parameters:
 
 - `serverNoContextTakeover` {Boolean} Whether to use context takeover or not.
 - `clientNoContextTakeover` {Boolean} Acknowledge disabling of client context
@@ -171,8 +171,8 @@ value). If an object is provided then that is extension parameters:
   above this limit will be queued. Default 10. You usually won't need to touch
   this option. See [this issue][concurrency-limit] for more details.
 
-If a property is empty then either an offered configuration or a default value
-is used. When sending a fragmented message the length of the first fragment is
+If a property is empty, then either an offered configuration or a default value
+is used. When sending a fragmented message, the length of the first fragment is
 compared to the threshold. This determines if compression is used for the entire
 message.
 
@@ -248,7 +248,7 @@ created internally. If an external HTTP server is used via the `server` or
 `noServer` constructor options, it must be closed manually. Existing connections
 are not closed automatically. The server emits a `'close'` event when all
 connections are closed unless an external HTTP server is used and client
-tracking is disabled. In this case the `'close'` event is emitted in the next
+tracking is disabled. In this case, the `'close'` event is emitted in the next
 tick. The optional callback is called when the `'close'` event occurs and
 receives an `Error` if the server is already closed.
 
@@ -273,7 +273,7 @@ If the upgrade is successful, the `callback` is called with two arguments:
 
 - `request` {http.IncomingMessage} The client HTTP GET request.
 
-See if a given request should be handled by this server. By default this method
+See if a given request should be handled by this server. By default, this method
 validates the pathname of the request, matching it against the `path` option if
 provided. The return value, `true` or `false`, determines whether or not to
 accept the handshake.
@@ -305,12 +305,12 @@ This class represents a WebSocket. It extends the `EventEmitter`.
     tick. To improve compatibility with the WHATWG standard, the default value
     is `false`. Setting it to `true` improves performance slightly.
   - `finishRequest` {Function} A function which can be used to customize the
-    headers of each http request before it is sent. See description below.
+    headers of each HTTP request before it is sent. See description below.
   - `followRedirects` {Boolean} Whether or not to follow redirects. Defaults to
     `false`.
   - `generateMask` {Function} The function used to generate the masking key. It
     takes a `Buffer` that must be filled synchronously and is called before a
-    message is sent, for each message. By default the buffer is filled with
+    message is sent, for each message. By default, the buffer is filled with
     cryptographically strong random bytes.
   - `handshakeTimeout` {Number} Timeout in milliseconds for the handshake
     request. This is reset after every redirection.
@@ -343,7 +343,7 @@ context takeover.
 
 for each HTTP GET request (the initial one and any caused by redirects) when it
 is ready to be sent, to allow for last minute customization of the headers. If
-`finishRequest` is set then it has the responsibility to call `request.end()`
+`finishRequest` is set, then it has the responsibility to call `request.end()`
 once it is done setting request headers. This is intended for niche use-cases
 where some headers can't be provided in advance e.g. because they depend on the
 underlying socket.
@@ -479,7 +479,7 @@ The number of bytes of data that have been queued using calls to `send()` but
 not yet transmitted to the network. This deviates from the HTML standard in the
 following ways:
 
-1. If the data is immediately sent the value is `0`.
+1. If the data is immediately sent, the value is `0`.
 1. All framing bytes are included.
 
 ### websocket.close([code[, reason]])
@@ -610,7 +610,7 @@ state is `CONNECTING`.
 
 ### websocket.terminate()
 
-Forcibly close the connection. Internally this calls [`socket.destroy()`][].
+Forcibly close the connection. Internally, this calls [`socket.destroy()`][].
 
 ### websocket.url
 
@@ -631,12 +631,12 @@ given `WebSocket`.
 
 ### WS_NO_BUFFER_UTIL
 
-When set to a non empty value, prevents the optional `bufferutil` dependency
+When set to a non-empty value, prevents the optional `bufferutil` dependency
 from being required.
 
 ### WS_NO_UTF_8_VALIDATE
 
-When set to a non empty value, prevents the optional `utf-8-validate` dependency
+When set to a non-empty value, prevents the optional `utf-8-validate` dependency
 from being required.
 
 ## Error codes