From b43caf92c0bf7be80802590ef074f907d557bb72 Mon Sep 17 00:00:00 2001 From: James M Snell Date: Tue, 1 Aug 2017 08:35:45 -0700 Subject: [PATCH] http2: fix documentation errors Backport-PR-URL: https://github.com/nodejs/node/pull/14813 Backport-Reviewed-By: Anna Henningsen Backport-Reviewed-By: Timothy Gu PR-URL: https://github.com/nodejs/node/pull/14239 Reviewed-By: Anna Henningsen Reviewed-By: Colin Ihrig Reviewed-By: Matteo Collina --- doc/api/http2.md | 78 ++++++++++++++++++++++++++---------------------- 1 file changed, 42 insertions(+), 36 deletions(-) diff --git a/doc/api/http2.md b/doc/api/http2.md index da6df4f7e6acac..29e08662af236a 100755 --- a/doc/api/http2.md +++ b/doc/api/http2.md @@ -1803,10 +1803,10 @@ req.end('Jane'); ## Compatibility API -The Compatibility API has the goal of providing a similar developer experience of -HTTP/1 when using HTTP/2, making it possible to develop applications -that supports both [HTTP/1](HTTP/1) and HTTP/2. This API targets only the **public -API** of the [HTTP/1](HTTP/1), however many modules uses internal +The Compatibility API has the goal of providing a similar developer experience +of HTTP/1 when using HTTP/2, making it possible to develop applications +that supports both [HTTP/1](HTTP/1) and HTTP/2. This API targets only the +**public API** of the [HTTP/1](HTTP/1), however many modules uses internal methods or state, and those _are not supported_ as it is a completely different implementation. @@ -1823,7 +1823,7 @@ const server = http2.createServer((req, res) => { }); ``` -In order to create a mixed [HTTPs](https) and HTTP/2 server, refer to the +In order to create a mixed [HTTPS](https) and HTTP/2 server, refer to the [ALPN negotiation](alpn-negotiation) section. Upgrading from non-tls HTTP/1 servers is not supported. @@ -1834,8 +1834,8 @@ the status message for HTTP codes is ignored. ### ALPN negotiation -ALPN negotiation allows to support both [HTTPs](https) and HTTP/2 over -the same socket. the `req` and `res` object could be either HTTP/1 or +ALPN negotiation allows to support both [HTTPS](https) and HTTP/2 over +the same socket. The `req` and `res` objects can be either HTTP/1 or HTTP/2, and an application **must** restrict itself to the public API of [HTTP/1](), and detect if it is possible to use the more advanced features of HTTP/2. @@ -1855,7 +1855,7 @@ const server = createSecureServer( ).listen(4443); function onRequest(req, res) { - // detects if it is a HTTPs request or HTTP/2 + // detects if it is a HTTPS request or HTTP/2 const { socket: { alpnProtocol } } = request.httpVersion === '2.0' ? request.stream.session : request; response.writeHead(200, { 'content-type': 'application/json' }); @@ -1866,7 +1866,7 @@ function onRequest(req, res) { } ``` -The `'request'` event works identically on both [HTTPs](https) and +The `'request'` event works identically on both [HTTPS](https) and HTTP/2. ### Class: http2.Http2ServerRequest @@ -1875,8 +1875,9 @@ added: REPLACEME --> A `Http2ServerRequest` object is created by [`http2.Server`][] or -[`http2.SecureServer`][] and passed as the first argument to the [`'request'`][] event. It may be used to access a request status, -headers and data. +[`http2.SecureServer`][] and passed as the first argument to the +[`'request'`][] event. It may be used to access a request status, headers and +data. It implements the [Readable Stream][] interface, as well as the following additional events, methods, and properties. @@ -1907,9 +1908,9 @@ added: REPLACEME * `error` {Error} -Calls `destroy()` on the [Http2Stream]() that received the `ServerRequest`. If `error` -is provided, an `'error'` event is emitted and `error` is passed as an argument -to any listeners on the event. +Calls `destroy()` on the [Http2Stream]() that received the `ServerRequest`. If +`error` is provided, an `'error'` event is emitted and `error` is passed as an +argument to any listeners on the event. It does nothing if the stream was already destroyed. @@ -2201,7 +2202,7 @@ added: REPLACEME * `name` {string} * Returns: {string} -Reads out a header that's already been queued but not sent to the client. +Reads out a header that has already been queued but not sent to the client. Note that the name is case insensitive. Example: @@ -2291,7 +2292,7 @@ added: REPLACEME * `name` {string} -Removes a header that's queued for implicit sending. +Removes a header that has been queued for implicit sending. Example: @@ -2339,9 +2340,9 @@ response.setHeader('Set-Cookie', ['type=ninja', 'language=javascript']); Attempting to set a header field name or value that contains invalid characters will result in a [`TypeError`][] being thrown. -When headers have been set with [`response.setHeader()`][], they will be merged with -any headers passed to [`response.writeHead()`][], with the headers passed to -[`response.writeHead()`][] given precedence. +When headers have been set with [`response.setHeader()`][], they will be merged +with any headers passed to [`response.writeHead()`][], with the headers passed +to [`response.writeHead()`][] given precedence. ```js // returns content-type = text/plain @@ -2366,9 +2367,9 @@ provided, then it is added as a listener on the `'timeout'` event on the response object. If no `'timeout'` listener is added to the request, the response, or -the server, then [`Http2Stream`]()s are destroyed when they time out. If a handler is -assigned to the request, the response, or the server's `'timeout'` events, -timed out sockets must be handled explicitly. +the server, then [`Http2Stream`]()s are destroyed when they time out. If a +handler is assigned to the request, the response, or the server's `'timeout'` +events, timed out sockets must be handled explicitly. Returns `response`. @@ -2478,7 +2479,8 @@ buffer. Returns `false` if all or part of the data was queued in user memory. added: REPLACEME --> -Throws an error as the `'continue'` flow is not current implemented. Added for parity with [HTTP/1](). +Throws an error as the `'continue'` flow is not current implemented. Added for +parity with [HTTP/1](). ### response.writeHead(statusCode[, statusMessage][, headers])