Skip to content

Commit 460a5b0

Browse files
committed
doc: copyedit http.OutgoingMessage documentation
Fix nits/typos and simplify some sentences.
1 parent e61b62b commit 460a5b0

File tree

1 file changed

+44
-68
lines changed

1 file changed

+44
-68
lines changed

doc/api/http.md

Lines changed: 44 additions & 68 deletions
Original file line numberDiff line numberDiff line change
@@ -2435,8 +2435,8 @@ added: v0.1.17
24352435
* Extends: {Stream}
24362436

24372437
This class serves as the parent class of [`http.ClientRequest`][]
2438-
and [`http.ServerResponse`][]. It is an abstract of outgoing message from
2439-
the perspective of the participants of HTTP transaction.
2438+
and [`http.ServerResponse`][]. It is an abstract outgoing message from
2439+
the perspective of the participants of an HTTP transaction.
24402440

24412441
### Event: `'drain'`
24422442

@@ -2460,7 +2460,7 @@ Emitted when the transmission is finished successfully.
24602460
added: v0.11.6
24612461
-->
24622462

2463-
Emitted when `outgoingMessage.end` was called.
2463+
Emitted after `outgoingMessage.end()` is called.
24642464
When the event is emitted, all data has been processed but not necessarily
24652465
completely flushed.
24662466

@@ -2474,11 +2474,11 @@ added: v0.3.0
24742474

24752475
Adds HTTP trailers (headers but at the end of the message) to the message.
24762476

2477-
Trailers are **only** be emitted if the message is chunked encoded. If not,
2478-
the trailer will be silently discarded.
2477+
Trailers will **only** be emitted if the message is chunked encoded. If not,
2478+
the trailers will be silently discarded.
24792479

24802480
HTTP requires the `Trailer` header to be sent to emit trailers,
2481-
with a list of header fields in its value, e.g.
2481+
with a list of header field names in its value, e.g.
24822482

24832483
```js
24842484
message.writeHead(200, { 'Content-Type': 'text/plain',
@@ -2502,7 +2502,7 @@ deprecated:
25022502

25032503
> Stability: 0 - Deprecated: Use [`outgoingMessage.socket`][] instead.
25042504
2505-
Aliases of `outgoingMessage.socket`
2505+
Alias of [`outgoingMessage.socket`][].
25062506

25072507
### `outgoingMessage.cork()`
25082508

@@ -2540,22 +2540,22 @@ changes:
25402540

25412541
Finishes the outgoing message. If any parts of the body are unsent, it will
25422542
flush them to the underlying system. If the message is chunked, it will
2543-
send the terminating chunk `0\r\n\r\n`, and send the trailer (if any).
2543+
send the terminating chunk `0\r\n\r\n`, and send the trailers (if any).
25442544

2545-
If `chunk` is specified, it is equivalent to call
2545+
If `chunk` is specified, it is equivalent to calling
25462546
`outgoingMessage.write(chunk, encoding)`, followed by
25472547
`outgoingMessage.end(callback)`.
25482548

2549-
If `callback` is provided, it will be called when the message is finished.
2550-
(equivalent to the callback to event `finish`)
2549+
If `callback` is provided, it will be called when the message is finished
2550+
(equivalent to a listener of the `'finish'` event).
25512551

25522552
### `outgoingMessage.flushHeaders()`
25532553

25542554
<!-- YAML
25552555
added: v1.6.0
25562556
-->
25572557

2558-
Compulsorily flushes the message headers
2558+
Flushes the message headers.
25592559

25602560
For efficiency reason, Node.js normally buffers the message headers
25612561
until `outgoingMessage.end()` is called or the first chunk of message data
@@ -2564,7 +2564,7 @@ packet.
25642564

25652565
It is usually desired (it saves a TCP round-trip), but not when the first
25662566
data is not sent until possibly much later. `outgoingMessage.flushHeaders()`
2567-
bypasses the optimization and kickstarts the request.
2567+
bypasses the optimization and kickstarts the message.
25682568

25692569
### `outgoingMessage.getHeader(name)`
25702570

@@ -2575,8 +2575,8 @@ added: v0.4.0
25752575
* `name` {string} Name of header
25762576
* Returns {string | undefined}
25772577

2578-
Gets the value of HTTP header with the given name. If such a name doesn't
2579-
exist in message, it will be `undefined`.
2578+
Gets the value of the HTTP header with the given name. If that header is not
2579+
set, the returned value will be `undefined`.
25802580

25812581
### `outgoingMessage.getHeaderNames()`
25822582

@@ -2586,8 +2586,8 @@ added: v7.7.0
25862586

25872587
* Returns {string\[]}
25882588

2589-
Returns an array of names of headers of the outgoing outgoingMessage. All
2590-
names are lowercase.
2589+
Returns an array containing the unique names of names of the current outgoing
2590+
headers. All names are lowercase.
25912591

25922592
### `outgoingMessage.getHeaders()`
25932593

@@ -2604,8 +2604,8 @@ object are the header names and the values are the respective header
26042604
values. All header names are lowercase.
26052605

26062606
The object returned by the `outgoingMessage.getHeaders()` method does
2607-
not prototypically inherit from the JavaScript Object. This means that
2608-
typical Object methods such as `obj.toString()`, `obj.hasOwnProperty()`,
2607+
not prototypically inherit from the JavaScript `Object`. This means that
2608+
typical `Object` methods such as `obj.toString()`, `obj.hasOwnProperty()`,
26092609
and others are not defined and will not work.
26102610

26112611
```js
@@ -2648,14 +2648,11 @@ Read-only. `true` if the headers were sent, otherwise `false`.
26482648
added: v9.0.0
26492649
-->
26502650

2651-
Overrides the pipe method of legacy `Stream` which is the parent class of
2652-
`http.outgoingMessage`.
2651+
Overrides the `stream.pipe()` method inherited from the legacy `Stream` class
2652+
which is the parent class of `http.OutgoingMessage`.
26532653

2654-
Since `OutgoingMessage` should be a write-only stream,
2655-
call this function will throw an `Error`. Thus, it disabled the pipe method
2656-
it inherits from `Stream`.
2657-
2658-
The User should not call this function directly.
2654+
Calling this method will throw an `Error` because `outgoingMessage` is a
2655+
write-only stream.
26592656

26602657
### `outgoingMessage.removeHeader(name)`
26612658

@@ -2678,10 +2675,12 @@ added: v0.4.0
26782675
-->
26792676

26802677
* `name` {string} Header name
2681-
* `value` {string} Header value
2678+
* `value` {any} Header value
26822679
* Returns: {this}
26832680

2684-
Sets a single header value for the header object.
2681+
Sets a single header value. If the header already exists in the to-be-sent
2682+
headers, its value will be replaced. Use an array of strings to send multiple
2683+
headers with the same name.
26852684

26862685
### `outgoingMessage.setTimeout(msesc[, callback])`
26872686

@@ -2726,8 +2725,7 @@ added: v14.0.0
27262725

27272726
* {number}
27282727

2729-
This `outgoingMessage.writableCorked` will return the time how many
2730-
`outgoingMessage.cork()` have been called.
2728+
The number of times `outgoingMessage.cork()` has been called.
27312729

27322730
### `outgoingMessage.writableEnded`
27332731

@@ -2737,9 +2735,9 @@ added: v13.0.0
27372735

27382736
* {boolean}
27392737

2740-
Readonly, `true` if `outgoingMessage.end()` has been called. Noted that
2741-
this property does not reflect whether the data has been flush. For that
2742-
purpose, use `message.writableFinished` instead.
2738+
Is `true` if `outgoingMessage.end()` has been called. This property does
2739+
not indicate whether the data has been flushed. For that purpose, use
2740+
`message.writableFinished` instead.
27432741

27442742
### `outgoingMessage.writableFinished`
27452743

@@ -2749,7 +2747,7 @@ added: v13.0.0
27492747

27502748
* {boolean}
27512749

2752-
Readonly. `true` if all data has been flushed to the underlying system.
2750+
Is `true` if all data has been flushed to the underlying system.
27532751

27542752
### `outgoingMessage.writableHighWaterMark`
27552753

@@ -2759,12 +2757,8 @@ added: v13.0.0
27592757

27602758
* {number}
27612759

2762-
This `outgoingMessage.writableHighWaterMark` will be the `highWaterMark` of
2763-
underlying socket if socket exists. Else, it would be the default
2764-
`highWaterMark`.
2765-
2766-
`highWaterMark` is the maximum amount of data that can be potentially
2767-
buffered by the socket.
2760+
The `highWaterMark` of the underlying socket if assigned. Otherwise, the default
2761+
buffer level when [`writable.write()`][] starts returning false (`16384`).
27682762

27692763
### `outgoingMessage.writableLength`
27702764

@@ -2774,8 +2768,7 @@ added: v13.0.0
27742768

27752769
* {number}
27762770

2777-
Readonly, This `outgoingMessage.writableLength` contains the number of
2778-
bytes (or objects) in the buffer ready to send.
2771+
The number of buffered bytes.
27792772

27802773
### `outgoingMessage.writableObjectMode`
27812774

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

27862779
* {boolean}
27872780

2788-
Readonly, always returns `false`.
2781+
Always `false`.
27892782

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

27922785
<!-- YAML
27932786
added: v0.1.29
27942787
changes:
27952788
- version: v0.11.6
2796-
description: add `callback` argument.
2789+
description: The `callback` argument was added.
27972790
-->
27982791

27992792
* `chunk` {string | Buffer}
28002793
* `encoding` {string} **Default**: `utf8`
28012794
* `callback` {Function}
28022795
* Returns {boolean}
28032796

2804-
If this method is called and the header is not sent, it will call
2805-
`this._implicitHeader` to flush implicit header.
2806-
If the message should not have a body (indicated by `this._hasBody`),
2807-
the call is ignored and `chunk` will not be sent. It could be useful
2808-
when handling a particular message which must not include a body.
2809-
e.g. response to `HEAD` request, `204` and `304` response.
2810-
2811-
`chunk` can be a string or a buffer. When `chunk` is a string, the
2812-
`encoding` parameter specifies how to encode `chunk` into a byte stream.
2813-
`callback` will be called when the `chunk` is flushed.
2797+
Sends a chunk of the body. This method can be called multiple times.
28142798

2815-
If the message is transferred in chucked encoding
2816-
(indicated by `this.chunkedEncoding`), `chunk` will be flushed as
2817-
one chunk among a stream of chunks. Otherwise, it will be flushed as the
2818-
body of message.
2799+
The `encoding` argument is only relevant when `chunk` is a string. Defaults to
2800+
`'utf8'`.
28192801

2820-
This method handles the raw body of the HTTP message and has nothing to do
2821-
with higher-level multi-part body encodings that may be used.
2822-
2823-
If it is the first call to this method of a message, it will send the
2824-
buffered header first, then flush the `chunk` as described above.
2825-
2826-
The second and successive calls to this method will assume the data
2827-
will be streamed and send the new data separately. It means that the response
2828-
is buffered up to the first chunk of the body.
2802+
The `callback` argument is optional and will be called when this chunk of data
2803+
is flushed.
28292804

28302805
Returns `true` if the entire data was flushed successfully to the kernel
28312806
buffer. Returns `false` if all or part of the data was queued in the user
2832-
memory. Event `drain` will be emitted when the buffer is free again.
2807+
memory. The `'drain'` event will be emitted when the buffer is free again.
28332808

28342809
## `http.METHODS`
28352810

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

0 commit comments

Comments
 (0)