doc: copyedit http.OutgoingMessage documentation

Fix nits/typos and simplify some sentences.

PR-URL: https://github.com/nodejs/node/pull/42733
Reviewed-By: Paolo Insogna <paolo@cowtech.it>
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>

1 files changed, 44 insertions, 68 deletions

diff --git a/doc/api/http.md b/doc/api/http.md
index f8a4bb163f..0174908eb5 100644
--- a/doc/api/http.md
+++ b/doc/api/http.md
@@ -2455,8 +2455,8 @@ added: v0.1.17
 * Extends: {Stream}
 
 This class serves as the parent class of [`http.ClientRequest`][]
-and [`http.ServerResponse`][]. It is an abstract of outgoing message from
-the perspective of the participants of HTTP transaction.
+and [`http.ServerResponse`][]. It is an abstract outgoing message from
+the perspective of the participants of an HTTP transaction.
 
 ### Event: `'drain'`
 
@@ -2480,7 +2480,7 @@ Emitted when the transmission is finished successfully.
 added: v0.11.6
 -->
 
-Emitted when `outgoingMessage.end` was called.
+Emitted after `outgoingMessage.end()` is called.
 When the event is emitted, all data has been processed but not necessarily
 completely flushed.
 
@@ -2494,11 +2494,11 @@ added: v0.3.0
 
 Adds HTTP trailers (headers but at the end of the message) to the message.
 
-Trailers are **only** be emitted if the message is chunked encoded. If not,
-the trailer will be silently discarded.
+Trailers will **only** be emitted if the message is chunked encoded. If not,
+the trailers will be silently discarded.
 
 HTTP requires the  `Trailer` header to be sent to emit trailers,
-with a list of header fields in its value, e.g.
+with a list of header field names in its value, e.g.
 
 ```js
 message.writeHead(200, { 'Content-Type': 'text/plain',
@@ -2522,7 +2522,7 @@ deprecated:
 
 > Stability: 0 - Deprecated: Use [`outgoingMessage.socket`][] instead.
 
-Aliases of `outgoingMessage.socket`
+Alias of [`outgoingMessage.socket`][].
 
 ### `outgoingMessage.cork()`
 
@@ -2562,14 +2562,14 @@ changes:
 
 Finishes the outgoing message. If any parts of the body are unsent, it will
 flush them to the underlying system. If the message is chunked, it will
-send the terminating chunk `0\r\n\r\n`, and send the trailer (if any).
+send the terminating chunk `0\r\n\r\n`, and send the trailers (if any).
 
-If `chunk` is specified, it is equivalent to call
+If `chunk` is specified, it is equivalent to calling
 `outgoingMessage.write(chunk, encoding)`, followed by
 `outgoingMessage.end(callback)`.
 
-If `callback` is provided, it will be called when the message is finished.
-(equivalent to the callback to event `finish`)
+If `callback` is provided, it will be called when the message is finished
+(equivalent to a listener of the `'finish'` event).
 
 ### `outgoingMessage.flushHeaders()`
 
@@ -2577,7 +2577,7 @@ If `callback` is provided, it will be called when the message is finished.
 added: v1.6.0
 -->
 
-Compulsorily flushes the message headers
+Flushes the message headers.
 
 For efficiency reason, Node.js normally buffers the message headers
 until `outgoingMessage.end()` is called or the first chunk of message data
@@ -2586,7 +2586,7 @@ packet.
 
 It is usually desired (it saves a TCP round-trip), but not when the first
 data is not sent until possibly much later. `outgoingMessage.flushHeaders()`
-bypasses the optimization and kickstarts the request.
+bypasses the optimization and kickstarts the message.
 
 ### `outgoingMessage.getHeader(name)`
 
@@ -2597,8 +2597,8 @@ added: v0.4.0
 * `name` {string} Name of header
 * Returns {string | undefined}
 
-Gets the value of HTTP header with the given name. If such a name doesn't
-exist in message, it will be `undefined`.
+Gets the value of the HTTP header with the given name. If that header is not
+set, the returned value will be `undefined`.
 
 ### `outgoingMessage.getHeaderNames()`
 
@@ -2608,8 +2608,8 @@ added: v7.7.0
 
 * Returns {string\[]}
 
-Returns an array of names of headers of the outgoing outgoingMessage. All
-names are lowercase.
+Returns an array containing the unique names of the current outgoing headers.
+All names are lowercase.
 
 ### `outgoingMessage.getHeaders()`
 
@@ -2626,8 +2626,8 @@ object are the header names and the values are the respective header
 values. All header names are lowercase.
 
 The object returned by the `outgoingMessage.getHeaders()` method does
-not prototypically inherit from the JavaScript Object. This means that
-typical Object methods such as `obj.toString()`, `obj.hasOwnProperty()`,
+not prototypically inherit from the JavaScript `Object`. This means that
+typical `Object` methods such as `obj.toString()`, `obj.hasOwnProperty()`,
 and others are not defined and will not work.
 
 ```js
@@ -2670,14 +2670,11 @@ Read-only. `true` if the headers were sent, otherwise `false`.
 added: v9.0.0
 -->
 
-Overrides the pipe method of legacy `Stream` which is the parent class of
-`http.outgoingMessage`.
-
-Since `OutgoingMessage` should be a write-only stream,
-call this function will throw an `Error`. Thus, it disabled the pipe method
-it inherits from `Stream`.
+Overrides the `stream.pipe()` method inherited from the legacy `Stream` class
+which is the parent class of `http.OutgoingMessage`.
 
-The User should not call this function directly.
+Calling this method will throw an `Error` because `outgoingMessage` is a
+write-only stream.
 
 ### `outgoingMessage.removeHeader(name)`
 
@@ -2700,10 +2697,12 @@ added: v0.4.0
 -->
 
 * `name` {string} Header name
-* `value` {string} Header value
+* `value` {any} Header value
 * Returns: {this}
 
-Sets a single header value for the header object.
+Sets a single header value. If the header already exists in the to-be-sent
+headers, its value will be replaced. Use an array of strings to send multiple
+headers with the same name.
 
 ### `outgoingMessage.setTimeout(msesc[, callback])`
 
@@ -2752,8 +2751,7 @@ added:
 
 * {number}
 
-This `outgoingMessage.writableCorked` will return the time how many
-`outgoingMessage.cork()` have been called.
+The number of times `outgoingMessage.cork()` has been called.
 
 ### `outgoingMessage.writableEnded`
 
@@ -2763,9 +2761,9 @@ added: v12.9.0
 
 * {boolean}
 
-Readonly, `true` if `outgoingMessage.end()` has been called. Noted that
-this property does not reflect whether the data has been flush. For that
-purpose, use `message.writableFinished` instead.
+Is `true` if `outgoingMessage.end()` has been called. This property does
+not indicate whether the data has been flushed. For that purpose, use
+`message.writableFinished` instead.
 
 ### `outgoingMessage.writableFinished`
 
@@ -2775,7 +2773,7 @@ added: v12.7.0
 
 * {boolean}
 
-Readonly. `true` if all data has been flushed to the underlying system.
+Is `true` if all data has been flushed to the underlying system.
 
 ### `outgoingMessage.writableHighWaterMark`
 
@@ -2785,12 +2783,8 @@ added: v12.9.0
 
 * {number}
 
-This `outgoingMessage.writableHighWaterMark` will be the `highWaterMark` of
-underlying socket if socket exists. Else, it would be the default
-`highWaterMark`.
-
-`highWaterMark` is the maximum amount of data that can be potentially
-buffered by the socket.
+The `highWaterMark` of the underlying socket if assigned. Otherwise, the default
+buffer level when [`writable.write()`][] starts returning false (`16384`).
 
 ### `outgoingMessage.writableLength`
 
@@ -2800,8 +2794,7 @@ added: v12.9.0
 
 * {number}
 
-Readonly, This `outgoingMessage.writableLength` contains the number of
-bytes (or objects) in the buffer ready to send.
+The number of buffered bytes.
 
 ### `outgoingMessage.writableObjectMode`
 
@@ -2811,7 +2804,7 @@ added: v12.9.0
 
 * {boolean}
 
-Readonly, always returns `false`.
+Always `false`.
 
 ### `outgoingMessage.write(chunk[, encoding][, callback])`
 
@@ -2819,7 +2812,7 @@ Readonly, always returns `false`.
 added: v0.1.29
 changes:
   - version: v0.11.6
-    description: add `callback` argument.
+    description: The `callback` argument was added.
 -->
 
 * `chunk` {string | Buffer}
@@ -2827,35 +2820,17 @@ changes:
 * `callback` {Function}
 * Returns {boolean}
 
-If this method is called and the header is not sent, it will call
-`this._implicitHeader` to flush implicit header.
-If the message should not have a body (indicated by `this._hasBody`),
-the call is ignored and `chunk` will not be sent. It could be useful
-when handling a particular message which must not include a body.
-e.g. response to `HEAD` request, `204` and `304` response.
+Sends a chunk of the body. This method can be called multiple times.
 
-`chunk` can be a string or a buffer. When `chunk` is a string, the
-`encoding` parameter specifies how to encode `chunk` into a byte stream.
-`callback` will be called when the `chunk` is flushed.
+The `encoding` argument is only relevant when `chunk` is a string. Defaults to
+`'utf8'`.
 
-If the message is transferred in chucked encoding
-(indicated by `this.chunkedEncoding`), `chunk` will be flushed as
-one chunk among a stream of chunks. Otherwise, it will be flushed as the
-body of message.
-
-This method handles the raw body of the HTTP message and has nothing to do
-with higher-level multi-part body encodings that may be used.
-
-If it is the first call to this method of a message, it will send the
-buffered header first, then flush the `chunk` as described above.
-
-The second and successive calls to this method will assume the data
-will be streamed and send the new data separately. It means that the response
-is buffered up to the first chunk of the body.
+The `callback` argument is optional and will be called when this chunk of data
+is flushed.
 
 Returns `true` if the entire data was flushed successfully to the kernel
 buffer. Returns `false` if all or part of the data was queued in the user
-memory. Event `drain` will be emitted when the buffer is free again.
+memory. The `'drain'` event will be emitted when the buffer is free again.
 
 ## `http.METHODS`
 
@@ -3542,4 +3517,5 @@ try {
 [`writable.destroy()`]: stream.md#writabledestroyerror
 [`writable.destroyed`]: stream.md#writabledestroyed
 [`writable.uncork()`]: stream.md#writableuncork
+[`writable.write()`]: stream.md#writablewritechunk-encoding-callback
 [initial delay]: net.md#socketsetkeepaliveenable-initialdelay