From 8bd61d4c3859f255e1302fd3625ab22c6c7d1c0b Mon Sep 17 00:00:00 2001
From: James M Snell <jasnell@gmail.com>
Date: Wed, 15 Jul 2020 17:14:03 -0700
Subject: [PATCH] quic: documentation updates

PR-URL: https://github.com/nodejs/node/pull/34351
Reviewed-By: Robert Nagy <ronagy@icloud.com>
Reviewed-By: Anna Henningsen <anna@addaleax.net>
---
 doc/api/quic.md | 71 +++++++++++++++++++++++++++++++++++++------------
 1 file changed, 54 insertions(+), 17 deletions(-)

diff --git a/doc/api/quic.md b/doc/api/quic.md
index a6cd2ecd91c4b7..f23078dbc588bd 100644
--- a/doc/api/quic.md
+++ b/doc/api/quic.md
@@ -2115,15 +2115,6 @@ stream('initialHeaders', (headers) => {
 });
 ```
 
-#### Event: `'ready'`
-<!-- YAML
-added: REPLACEME
--->
-
-Emitted when the underlying `QuicSession` has emitted its `secure` event
-this stream has received its id, which is accessible as `stream.id` once this
-event is emitted.
-
 #### Event: `'trailingHeaders'`
 <!-- YAML
 added: REPLACEME
@@ -2158,7 +2149,10 @@ added: REPLACEME
 
 * Type: {boolean}
 
-Set to `true` if the `QuicStream` is bidirectional.
+When `true`, the `QuicStream` is bidirectional. Both the readable and
+writable sides of the `QuicStream` `Duplex` are open.
+
+Read-only.
 
 #### `quicstream.bytesReceived`
 <!-- YAML
@@ -2169,6 +2163,8 @@ added: REPLACEME
 
 The total number of bytes received for this `QuicStream`.
 
+Read-only.
+
 #### `quicstream.bytesSent`
 <!-- YAML
 added: REPLACEME
@@ -2178,6 +2174,8 @@ added: REPLACEME
 
 The total number of bytes sent by this `QuicStream`.
 
+Read-only.
+
 #### `quicstream.clientInitiated`
 <!-- YAML
 added: REPLACEME
@@ -2185,17 +2183,20 @@ added: REPLACEME
 
 * Type: {boolean}
 
-Set to `true` if the `QuicStream` was initiated by a `QuicClientSession`
+Will be `true` if the `QuicStream` was initiated by a `QuicClientSession`
 instance.
 
-#### `quicstream.close(code)`
+Read-only.
+
+#### `quicstream.close()`
 <!-- YAML
 added: REPLACEME
 -->
 
-* `code` {number}
+* Returns: {Promise`}
 
-Closes the `QuicStream`.
+Closes the `QuicStream` by ending both sides of the `QuicStream` `Duplex`.
+Returns a `Promise` that is resolved once the `QuicStream` has been destroyed.
 
 #### `quicstream.dataAckHistogram`
 <!-- YAML
@@ -2226,6 +2227,8 @@ added: REPLACEME
 
 The length of time the `QuicStream` has been active.
 
+Read-only.
+
 #### `quicstream.finalSize`
 <!-- YAML
 added: REPLACEME
@@ -2235,6 +2238,8 @@ added: REPLACEME
 
 The total number of bytes successfully received by the `QuicStream`.
 
+Read-only.
+
 #### `quicstream.id`
 <!-- YAML
 added: REPLACEME
@@ -2244,6 +2249,8 @@ added: REPLACEME
 
 The numeric identifier of the `QuicStream`.
 
+Read-only.
+
 #### `quicstream.maxAcknowledgedOffset`
 <!-- YAML
 added: REPLACEME
@@ -2253,6 +2260,8 @@ added: REPLACEME
 
 The highest acknowledged data offset received for this `QuicStream`.
 
+Read-only.
+
 #### `quicstream.maxExtendedOffset`
 <!-- YAML
 added: REPLACEME
@@ -2262,6 +2271,8 @@ added: REPLACEME
 
 The maximum extended data offset that has been reported to the connected peer.
 
+Read-only.
+
 #### `quicstream.maxReceivedOffset`
 <!-- YAML
 added: REPLACEME
@@ -2271,6 +2282,8 @@ added: REPLACEME
 
 The maximum received offset for this `QuicStream`.
 
+Read-only.
+
 #### `quicstream.pushStream(headers\[, options\])`
 <!-- YAML
 added: REPLACEME
@@ -2304,9 +2317,11 @@ added: REPLACEME
 
 * Type: {boolean}
 
-Set to `true` if the `QuicStream` was initiated by a `QuicServerSession`
+Will be `true` if the `QuicStream` was initiated by a `QuicServerSession`
 instance.
 
+Read-only.
+
 #### `quicstream.session`
 <!-- YAML
 added: REPLACEME
@@ -2314,7 +2329,10 @@ added: REPLACEME
 
 * Type: {QuicSession}
 
-The `QuicServerSession` or `QuicClientSession`.
+The `QuicServerSession` or `QuicClientSession` to which the
+`QuicStream` belongs.
+
+Read-only.
 
 #### `quicstream.sendFD(fd\[, options\])`
 <!-- YAML
@@ -2395,7 +2413,26 @@ added: REPLACEME
 
 * Type: {boolean}
 
-Set to `true` if the `QuicStream` is unidirectional.
+Will be `true` if the `QuicStream` is undirectional. Whether the `QuicStream`
+will be readable or writable depends on whether the `quicstream.session` is
+a `QuicClientSession` or `QuicServerSession`, and whether the `QuicStream`
+was initiated locally or remotely.
+
+| `quicstream.session` | `quicstream.serverInitiated` | Readable | Writable |
+| -------------------- | ---------------------------- | -------- | -------- |
+|  `QuicClientSession` |            `true`            |     Y    |     N    |
+|  `QuicServerSession` |            `true`            |     N    |     Y    |
+|  `QuicClientSession` |            `false`           |     N    |     Y    |
+|  `QuicServerSession` |            `false`           |     Y    |     N    |
+
+| `quicstream.session` | `quicstream.clientInitiated` | Readable | Writable |
+| -------------------- | ---------------------------- | -------- | -------- |
+|  `QuicClientSession` |            `true`            |     N    |     Y    |
+|  `QuicServerSession` |            `true`            |     Y    |     N    |
+|  `QuicClientSession` |            `false`           |     Y    |     N    |
+|  `QuicServerSession` |            `false`           |     N    |     Y    |
+
+Read-only.
 
 ## Additional notes