doc: add descriptions of state properties

Fixes: #15268

PR-URL: #18044
Fixes: #15268
Reviewed-By: Anna Henningsen <[email protected]>
Reviewed-By: Luigi Pinca <[email protected]>

Author: jasnell

doc/api/http2.md

@@ -527,16 +527,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`.
 
@@ -853,14 +865,21 @@ req.setTimeout(5000, () => req.rstWithCancel());
 <!-- 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`.