From 52d0f1c5d92b911dc7bedd1a3823c8d3c12c5267 Mon Sep 17 00:00:00 2001
From: James M Snell <jasnell@gmail.com>
Date: Mon, 8 Jan 2018 11:30:57 -0800
Subject: [PATCH] doc: add descriptions of state properties

Fixes: https://github.com/nodejs/node/issues/15268

PR-URL: https://github.com/nodejs/node/pull/18044
Fixes: https://github.com/nodejs/node/issues/15268
Reviewed-By: Anna Henningsen <anna@addaleax.net>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
---
 doc/api/http2.md | 49 +++++++++++++++++++++++++++++++++---------------
 1 file changed, 34 insertions(+), 15 deletions(-)

diff --git a/doc/api/http2.md b/doc/api/http2.md
index a67fc387d832a2..fc64f5ab9dd5da 100644
--- a/doc/api/http2.md
+++ b/doc/api/http2.md
@@ -540,16 +540,28 @@ All other interactions will be routed directly to the socket.
 added: v8.4.0
 -->
 
+Provides miscellaneous information about the current state of the
+`Http2Session`.
+
 * Value: {Object}
-  * `effectiveLocalWindowSize` {number}
-  * `effectiveRecvDataLength` {number}
-  * `nextStreamID` {number}
-  * `localWindowSize` {number}
-  * `lastProcStreamID` {number}
-  * `remoteWindowSize` {number}
-  * `outboundQueueSize` {number}
-  * `deflateDynamicTableSize` {number}
-  * `inflateDynamicTableSize` {number}
+  * `effectiveLocalWindowSize` {number} The current local (receive)
+    flow control window size for the `Http2Session`.
+  * `effectiveRecvDataLength` {number} The current number of bytes
+    that have been received since the last flow control `WINDOW_UPDATE`.
+  * `nextStreamID` {number} The numeric identifier to be used the
+    next time a new `Http2Stream` is created by this `Http2Session`.
+  * `localWindowSize` {number} The number of bytes that the remote peer can
+    send without receiving a `WINDOW_UPDATE`.
+  * `lastProcStreamID` {number} The numeric id of the `Http2Stream`
+    for which a `HEADERS` or `DATA` frame was most recently received.
+  * `remoteWindowSize` {number} The number of bytes that this `Http2Session`
+    may send without receiving a `WINDOW_UPDATE`.
+  * `outboundQueueSize` {number} The number of frames currently within the
+    outbound queue for this `Http2Session`.
+  * `deflateDynamicTableSize` {number} The current size in bytes of the
+    outbound header compression state table.
+  * `inflateDynamicTableSize` {number} The current size in bytes of the
+    inbound header compression state table.
 
 An object describing the current status of this `Http2Session`.
 
@@ -1010,14 +1022,21 @@ req.setTimeout(5000, () => req.rstStream(NGHTTP2_CANCEL));
 <!-- YAML
 added: v8.4.0
 -->
+Provides miscellaneous information about the current state of the
+`Http2Stream`.
 
 * Value: {Object}
-  * `localWindowSize` {number}
-  * `state` {number}
-  * `localClose` {number}
-  * `remoteClose` {number}
-  * `sumDependencyWeight` {number}
-  * `weight` {number}
+  * `localWindowSize` {number} The number of bytes the connected peer may send
+    for this `Http2Stream` without receiving a `WINDOW_UPDATE`.
+  * `state` {number} A flag indicating the low-level current state of the
+    `Http2Stream` as determined by nghttp2.
+  * `localClose` {number} `true` if this `Http2Stream` has been closed locally.
+  * `remoteClose` {number} `true` if this `Http2Stream` has been closed
+    remotely.
+  * `sumDependencyWeight` {number} The sum weight of all `Http2Stream`
+    instances that depend on this `Http2Stream` as specified using
+    `PRIORITY` frames.
+  * `weight` {number} The priority weight of this `Http2Stream`.
 
 A current state of this `Http2Stream`.