Skip to content

Commit

Permalink
doc: copyedit http.OutgoingMessage documentation
Browse files Browse the repository at this point in the history
Fix nits/typos and simplify some sentences.
  • Loading branch information
lpinca committed Apr 14, 2022
1 parent e61b62b commit 460a5b0
Showing 1 changed file with 44 additions and 68 deletions.
112 changes: 44 additions & 68 deletions doc/api/http.md
Original file line number Diff line number Diff line change
Expand Up @@ -2435,8 +2435,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'`

Expand All @@ -2460,7 +2460,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.

Expand All @@ -2474,11 +2474,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',
Expand All @@ -2502,7 +2502,7 @@ deprecated:

> Stability: 0 - Deprecated: Use [`outgoingMessage.socket`][] instead.
Aliases of `outgoingMessage.socket`
Alias of [`outgoingMessage.socket`][].

### `outgoingMessage.cork()`

Expand Down Expand Up @@ -2540,22 +2540,22 @@ 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()`

<!-- YAML
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
Expand All @@ -2564,7 +2564,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)`

Expand All @@ -2575,8 +2575,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()`

Expand All @@ -2586,8 +2586,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 names of the current outgoing
headers. All names are lowercase.

### `outgoingMessage.getHeaders()`

Expand All @@ -2604,8 +2604,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
Expand Down Expand Up @@ -2648,14 +2648,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`.
Overrides the `stream.pipe()` method inherited from the legacy `Stream` class
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`.

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)`

Expand All @@ -2678,10 +2675,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])`

Expand Down Expand Up @@ -2726,8 +2725,7 @@ added: v14.0.0

* {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`

Expand All @@ -2737,9 +2735,9 @@ added: v13.0.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`

Expand All @@ -2749,7 +2747,7 @@ added: v13.0.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`

Expand All @@ -2759,12 +2757,8 @@ added: v13.0.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`

Expand All @@ -2774,8 +2768,7 @@ added: v13.0.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`

Expand All @@ -2785,51 +2778,33 @@ added: v13.0.0

* {boolean}

Readonly, always returns `false`.
Always `false`.

### `outgoingMessage.write(chunk[, encoding][, callback])`

<!-- YAML
added: v0.1.29
changes:
- version: v0.11.6
description: add `callback` argument.
description: The `callback` argument was added.
-->

* `chunk` {string | Buffer}
* `encoding` {string} **Default**: `utf8`
* `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.

`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.
Sends a chunk of the body. This method can be called multiple times.

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.
The `encoding` argument is only relevant when `chunk` is a string. Defaults to
`'utf8'`.

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`

Expand Down Expand Up @@ -3515,5 +3490,6 @@ try {
[`writable.cork()`]: stream.md#writablecork
[`writable.destroy()`]: stream.md#writabledestroyerror
[`writable.destroyed`]: stream.md#writabledestroyed
[`writable.write()`]: stream.md#writablewritechunk-encoding-callback
[`writable.uncork()`]: stream.md#writableuncork
[initial delay]: net.md#socketsetkeepaliveenable-initialdelay

0 comments on commit 460a5b0

Please sign in to comment.