Update doc

apiref.html

@@ -368,8 +368,8 @@ The stream is already closed; or the stream ID is invalid.</p>
 <dt id="c.NGHTTP2_ERR_STREAM_CLOSING">
 <tt class="descname">NGHTTP2_ERR_STREAM_CLOSING</tt><a class="headerlink" href="#c.NGHTTP2_ERR_STREAM_CLOSING" title="Permalink to this definition">¶</a></dt>
 <dd><p>(<tt class="docutils literal"><span class="pre">-511</span></tt>)
-RST_STREAM has been added to the outbound queue. The stream is in
+RST_STREAM has been added to the outbound queue.  The stream is
-closing state.</p>
+in closing state.</p>
 </dd></dl>
 
 <dl class="macro">
@@ -406,8 +406,8 @@ Another DATA frame has already been deferred.</p>
 <dt id="c.NGHTTP2_ERR_START_STREAM_NOT_ALLOWED">
 <tt class="descname">NGHTTP2_ERR_START_STREAM_NOT_ALLOWED</tt><a class="headerlink" href="#c.NGHTTP2_ERR_START_STREAM_NOT_ALLOWED" title="Permalink to this definition">¶</a></dt>
 <dd><p>(<tt class="docutils literal"><span class="pre">-516</span></tt>)
-Starting new stream is not allowed. (e.g., GOAWAY has been sent
+Starting new stream is not allowed (e.g., GOAWAY has been sent
-and/or received.</p>
+and/or received).</p>
 </dd></dl>
 
 <dl class="macro">
@@ -421,11 +421,11 @@ GOAWAY has already been sent.</p>
 <dt id="c.NGHTTP2_ERR_INVALID_HEADER_BLOCK">
 <tt class="descname">NGHTTP2_ERR_INVALID_HEADER_BLOCK</tt><a class="headerlink" href="#c.NGHTTP2_ERR_INVALID_HEADER_BLOCK" title="Permalink to this definition">¶</a></dt>
 <dd><p>(<tt class="docutils literal"><span class="pre">-518</span></tt>)
-The received frame contains the invalid header block. (e.g.,
+The received frame contains the invalid header block (e.g., There
-There are duplicate header names; or the header names are not
+are duplicate header names; or the header names are not encoded
-encoded in US-ASCII character set and not lower cased; or the
+in US-ASCII character set and not lower cased; or the header name
-header name is zero-length string; or the header value contains
+is zero-length string; or the header value contains multiple
-multiple in-sequence NUL bytes).</p>
+in-sequence NUL bytes).</p>
 </dd></dl>
 
 <dl class="macro">
@@ -513,8 +513,11 @@ not been fully processed yet.</p>
 <tt class="descname">NGHTTP2_ERR_FATAL</tt><a class="headerlink" href="#c.NGHTTP2_ERR_FATAL" title="Permalink to this definition">¶</a></dt>
 <dd><p>(<tt class="docutils literal"><span class="pre">-900</span></tt>)
 The errors &lt; <a class="reference internal" href="#c.NGHTTP2_ERR_FATAL" title="NGHTTP2_ERR_FATAL"><tt class="xref c c-macro docutils literal"><span class="pre">NGHTTP2_ERR_FATAL</span></tt></a> mean that the library is
-under unexpected condition and cannot process any further data
+under unexpected condition and processing was terminated (e.g.,
-reliably (e.g., out of memory).</p>
+out of memory).  If application receives this error code, it must
+stop using that <a class="reference internal" href="#c.nghttp2_session" title="nghttp2_session"><tt class="xref c c-type docutils literal"><span class="pre">nghttp2_session</span></tt></a> object and only allowed
+operation for that object is deallocate it using
+<a class="reference internal" href="#c.nghttp2_session_del" title="nghttp2_session_del"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_del()</span></tt></a>.</p>
 </dd></dl>
 
 <dl class="macro">
@@ -639,8 +642,8 @@ The ALTSVC frame.</p>
 <dl class="type">
 <dt id="c.nghttp2_flag">
 <tt class="descname">nghttp2_flag</tt><a class="headerlink" href="#c.nghttp2_flag" title="Permalink to this definition">¶</a></dt>
-<dd><p>The flags for HTTP/2 frames. This enum defines all flags for
+<dd><p>The flags for HTTP/2 frames.  This enum defines all flags for all
-frames, assuming that the same flag name has the same mask.</p>
+frames.</p>
 <dl class="macro">
 <dt id="c.NGHTTP2_FLAG_NONE">
 <tt class="descname">NGHTTP2_FLAG_NONE</tt><a class="headerlink" href="#c.NGHTTP2_FLAG_NONE" title="Permalink to this definition">¶</a></dt>
@@ -1071,22 +1074,22 @@ void *<tt class="descname">ptr</tt><a class="headerlink" href="#c.nghttp2_data_s
 <dt id="c.nghttp2_data_source_read_callback">
 typedef ssize_t <tt class="descname">(*nghttp2_data_source_read_callback)</tt><big>(</big><a class="reference internal" href="#c.nghttp2_session" title="nghttp2_session">nghttp2_session</a><em>&nbsp;*session</em>, int32_t<em>&nbsp;stream_id</em>, uint8_t<em>&nbsp;*buf</em>, size_t<em>&nbsp;length</em>, uint32_t<em>&nbsp;*data_flags</em>, <a class="reference internal" href="#c.nghttp2_data_source" title="nghttp2_data_source">nghttp2_data_source</a><em>&nbsp;*source</em>, void<em>&nbsp;*user_data</em><big>)</big><a class="headerlink" href="#c.nghttp2_data_source_read_callback" title="Permalink to this definition">¶</a></dt>
 <dd><p>Callback function invoked when the library wants to read data from
-the <em>source</em>. The read data is sent in the stream <em>stream_id</em>. The
+the <em>source</em>.  The read data is sent in the stream <em>stream_id</em>.
-implementation of this function must read at most <em>length</em> bytes of
+The implementation of this function must read at most <em>length</em>
-data from <em>source</em> (or possibly other places) and store them in
+bytes of data from <em>source</em> (or possibly other places) and store
-<em>buf</em> and return number of data stored in <em>buf</em>. If EOF is reached,
+them in <em>buf</em> and return number of data stored in <em>buf</em>.  If EOF is
-set <a class="reference internal" href="#c.NGHTTP2_DATA_FLAG_EOF" title="NGHTTP2_DATA_FLAG_EOF"><tt class="xref c c-macro docutils literal"><span class="pre">NGHTTP2_DATA_FLAG_EOF</span></tt></a> flag in <em>*data_falgs</em>.  If the
+reached, set <a class="reference internal" href="#c.NGHTTP2_DATA_FLAG_EOF" title="NGHTTP2_DATA_FLAG_EOF"><tt class="xref c c-macro docutils literal"><span class="pre">NGHTTP2_DATA_FLAG_EOF</span></tt></a> flag in <em>*data_falgs</em>.
-application wants to postpone DATA frames, (e.g., asynchronous I/O,
+If the application wants to postpone DATA frames (e.g.,
-or reading data blocks for long time), it is achieved by returning
+asynchronous I/O, or reading data blocks for long time), it is
-<a class="reference internal" href="#c.NGHTTP2_ERR_DEFERRED" title="NGHTTP2_ERR_DEFERRED"><tt class="xref c c-macro docutils literal"><span class="pre">NGHTTP2_ERR_DEFERRED</span></tt></a> without reading any data in this
+achieved by returning <a class="reference internal" href="#c.NGHTTP2_ERR_DEFERRED" title="NGHTTP2_ERR_DEFERRED"><tt class="xref c c-macro docutils literal"><span class="pre">NGHTTP2_ERR_DEFERRED</span></tt></a> without reading
-invocation.  The library removes DATA frame from the outgoing queue
+any data in this invocation.  The library removes DATA frame from
-temporarily.  To move back deferred DATA frame to outgoing queue,
+the outgoing queue temporarily.  To move back deferred DATA frame
-call <a class="reference internal" href="#c.nghttp2_session_resume_data" title="nghttp2_session_resume_data"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_resume_data()</span></tt></a>.  In case of error, there are
+to outgoing queue, call <a class="reference internal" href="#c.nghttp2_session_resume_data" title="nghttp2_session_resume_data"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_resume_data()</span></tt></a>.  In case
-2 choices. Returning <a class="reference internal" href="#c.NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE" title="NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE"><tt class="xref c c-macro docutils literal"><span class="pre">NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE</span></tt></a>
+of error, there are 2 choices. Returning
-will close the stream by issuing RST_STREAM with
+<a class="reference internal" href="#c.NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE" title="NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE"><tt class="xref c c-macro docutils literal"><span class="pre">NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE</span></tt></a> will close the stream
-<a class="reference internal" href="#c.NGHTTP2_INTERNAL_ERROR" title="NGHTTP2_INTERNAL_ERROR"><tt class="xref c c-macro docutils literal"><span class="pre">NGHTTP2_INTERNAL_ERROR</span></tt></a>.  Returning
+by issuing RST_STREAM with <a class="reference internal" href="#c.NGHTTP2_INTERNAL_ERROR" title="NGHTTP2_INTERNAL_ERROR"><tt class="xref c c-macro docutils literal"><span class="pre">NGHTTP2_INTERNAL_ERROR</span></tt></a>.
-<a class="reference internal" href="#c.NGHTTP2_ERR_CALLBACK_FAILURE" title="NGHTTP2_ERR_CALLBACK_FAILURE"><tt class="xref c c-macro docutils literal"><span class="pre">NGHTTP2_ERR_CALLBACK_FAILURE</span></tt></a> will signal the entire session
+Returning <a class="reference internal" href="#c.NGHTTP2_ERR_CALLBACK_FAILURE" title="NGHTTP2_ERR_CALLBACK_FAILURE"><tt class="xref c c-macro docutils literal"><span class="pre">NGHTTP2_ERR_CALLBACK_FAILURE</span></tt></a> will signal the
-failure.</p>
+entire session failure.</p>
 </dd></dl>
 
 <dl class="type">
@@ -1489,8 +1492,8 @@ uint16_t <tt class="descname">port</tt><a class="headerlink" href="#c.nghttp2_al
 <dt id="c.nghttp2_frame">
 <tt class="descname">nghttp2_frame</tt><a class="headerlink" href="#c.nghttp2_frame" title="Permalink to this definition">¶</a></dt>
 <dd><p>This union includes all frames to pass them to various function
-calls as nghttp2_frame type. The CONTINUATION frame is omitted from
+calls as nghttp2_frame type.  The CONTINUATION frame is omitted
-here because the library deals with it internally.</p>
+from here because the library deals with it internally.</p>
 <dl class="member">
 <dt id="c.nghttp2_frame.hd">
 <a class="reference internal" href="#c.nghttp2_frame_hd" title="nghttp2_frame_hd">nghttp2_frame_hd</a> <tt class="descname">hd</tt><a class="headerlink" href="#c.nghttp2_frame.hd" title="Permalink to this definition">¶</a></dt>
@@ -1567,14 +1570,14 @@ remote peer. The implementation of this function must send at most
 <em>length</em> bytes of data stored in <em>data</em>.  The <em>flags</em> is currently
 not used and always 0. It must return the number of bytes sent if
 it succeeds.  If it cannot send any single byte without blocking,
-it must return <a class="reference internal" href="#c.NGHTTP2_ERR_WOULDBLOCK" title="NGHTTP2_ERR_WOULDBLOCK"><tt class="xref c c-macro docutils literal"><span class="pre">NGHTTP2_ERR_WOULDBLOCK</span></tt></a>. For other errors, it
+it must return <a class="reference internal" href="#c.NGHTTP2_ERR_WOULDBLOCK" title="NGHTTP2_ERR_WOULDBLOCK"><tt class="xref c c-macro docutils literal"><span class="pre">NGHTTP2_ERR_WOULDBLOCK</span></tt></a>.  For other errors,
-must return <a class="reference internal" href="#c.NGHTTP2_ERR_CALLBACK_FAILURE" title="NGHTTP2_ERR_CALLBACK_FAILURE"><tt class="xref c c-macro docutils literal"><span class="pre">NGHTTP2_ERR_CALLBACK_FAILURE</span></tt></a>. The <em>user_data</em>
+it must return <a class="reference internal" href="#c.NGHTTP2_ERR_CALLBACK_FAILURE" title="NGHTTP2_ERR_CALLBACK_FAILURE"><tt class="xref c c-macro docutils literal"><span class="pre">NGHTTP2_ERR_CALLBACK_FAILURE</span></tt></a>.  The
-pointer is the third argument passed in to the call to
+<em>user_data</em> pointer is the third argument passed in to the call to
 <a class="reference internal" href="#c.nghttp2_session_client_new" title="nghttp2_session_client_new"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_client_new()</span></tt></a> or <a class="reference internal" href="#c.nghttp2_session_server_new" title="nghttp2_session_server_new"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_server_new()</span></tt></a>.</p>
 <p>This callback is required if the application uses
 <a class="reference internal" href="#c.nghttp2_session_send" title="nghttp2_session_send"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_send()</span></tt></a> to send data to the remote endpoint.  If
-the application uses <a class="reference internal" href="#c.nghttp2_session_mem_send" title="nghttp2_session_mem_send"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_mem_send()</span></tt></a> instead, this
+the application uses solely <a class="reference internal" href="#c.nghttp2_session_mem_send" title="nghttp2_session_mem_send"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_mem_send()</span></tt></a> instead,
-callback function is unnecessary.</p>
+this callback function is unnecessary.</p>
 </dd></dl>
 
 <dl class="type">
@@ -1583,25 +1586,25 @@ typedef ssize_t <tt class="descname">(*nghttp2_recv_callback)</tt><big>(</big><a
 <dd><p>Callback function invoked when <em>session</em> wants to receive data from
 the remote peer.  The implementation of this function must read at
 most <em>length</em> bytes of data and store it in <em>buf</em>.  The <em>flags</em> is
-currently not used and always 0. It must return the number of bytes
+currently not used and always 0.  It must return the number of
-written in <em>buf</em> if it succeeds. If it cannot read any single byte
+bytes written in <em>buf</em> if it succeeds.  If it cannot read any
-without blocking, it must return <a class="reference internal" href="#c.NGHTTP2_ERR_WOULDBLOCK" title="NGHTTP2_ERR_WOULDBLOCK"><tt class="xref c c-macro docutils literal"><span class="pre">NGHTTP2_ERR_WOULDBLOCK</span></tt></a>. If
+single byte without blocking, it must return
-it gets EOF before it reads any single byte, it must return
+<a class="reference internal" href="#c.NGHTTP2_ERR_WOULDBLOCK" title="NGHTTP2_ERR_WOULDBLOCK"><tt class="xref c c-macro docutils literal"><span class="pre">NGHTTP2_ERR_WOULDBLOCK</span></tt></a>.  If it gets EOF before it reads any
-<a class="reference internal" href="#c.NGHTTP2_ERR_EOF" title="NGHTTP2_ERR_EOF"><tt class="xref c c-macro docutils literal"><span class="pre">NGHTTP2_ERR_EOF</span></tt></a>. For other errors, it must return
+single byte, it must return <a class="reference internal" href="#c.NGHTTP2_ERR_EOF" title="NGHTTP2_ERR_EOF"><tt class="xref c c-macro docutils literal"><span class="pre">NGHTTP2_ERR_EOF</span></tt></a>.  For other
-<a class="reference internal" href="#c.NGHTTP2_ERR_CALLBACK_FAILURE" title="NGHTTP2_ERR_CALLBACK_FAILURE"><tt class="xref c c-macro docutils literal"><span class="pre">NGHTTP2_ERR_CALLBACK_FAILURE</span></tt></a>. Returning 0 is treated as
+errors, it must return <a class="reference internal" href="#c.NGHTTP2_ERR_CALLBACK_FAILURE" title="NGHTTP2_ERR_CALLBACK_FAILURE"><tt class="xref c c-macro docutils literal"><span class="pre">NGHTTP2_ERR_CALLBACK_FAILURE</span></tt></a>.
-<a class="reference internal" href="#c.NGHTTP2_ERR_WOULDBLOCK" title="NGHTTP2_ERR_WOULDBLOCK"><tt class="xref c c-macro docutils literal"><span class="pre">NGHTTP2_ERR_WOULDBLOCK</span></tt></a>. The <em>user_data</em> pointer is the
+Returning 0 is treated as <a class="reference internal" href="#c.NGHTTP2_ERR_WOULDBLOCK" title="NGHTTP2_ERR_WOULDBLOCK"><tt class="xref c c-macro docutils literal"><span class="pre">NGHTTP2_ERR_WOULDBLOCK</span></tt></a>.  The
-third argument passed in to the call to
+<em>user_data</em> pointer is the third argument passed in to the call to
 <a class="reference internal" href="#c.nghttp2_session_client_new" title="nghttp2_session_client_new"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_client_new()</span></tt></a> or <a class="reference internal" href="#c.nghttp2_session_server_new" title="nghttp2_session_server_new"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_server_new()</span></tt></a>.</p>
 <p>This callback is required if the application uses
-<a class="reference internal" href="#c.nghttp2_session_recv" title="nghttp2_session_recv"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_recv()</span></tt></a> to receive data from the remote
+<a class="reference internal" href="#c.nghttp2_session_recv" title="nghttp2_session_recv"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_recv()</span></tt></a> to receive data from the remote endpoint.
-endpoint. If the application uses <a class="reference internal" href="#c.nghttp2_session_mem_recv" title="nghttp2_session_mem_recv"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_mem_recv()</span></tt></a>
+If the application uses solely <a class="reference internal" href="#c.nghttp2_session_mem_recv" title="nghttp2_session_mem_recv"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_mem_recv()</span></tt></a>
 instead, this callback function is unnecessary.</p>
 </dd></dl>
 
 <dl class="type">
 <dt id="c.nghttp2_on_frame_recv_callback">
 typedef int <tt class="descname">(*nghttp2_on_frame_recv_callback)</tt><big>(</big><a class="reference internal" href="#c.nghttp2_session" title="nghttp2_session">nghttp2_session</a><em>&nbsp;*session</em>, const <a class="reference internal" href="#c.nghttp2_frame" title="nghttp2_frame">nghttp2_frame</a><em>&nbsp;*frame</em>, void<em>&nbsp;*user_data</em><big>)</big><a class="headerlink" href="#c.nghttp2_on_frame_recv_callback" title="Permalink to this definition">¶</a></dt>
-<dd><p>Callback function invoked by <a class="reference internal" href="#c.nghttp2_session_recv" title="nghttp2_session_recv"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_recv()</span></tt></a> when a aframe
+<dd><p>Callback function invoked by <a class="reference internal" href="#c.nghttp2_session_recv" title="nghttp2_session_recv"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_recv()</span></tt></a> when a frame
 is received.  The <em>user_data</em> pointer is the third argument passed
 in to the call to <a class="reference internal" href="#c.nghttp2_session_client_new" title="nghttp2_session_client_new"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_client_new()</span></tt></a> or
 <a class="reference internal" href="#c.nghttp2_session_server_new" title="nghttp2_session_server_new"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_server_new()</span></tt></a>.</p>
@@ -1614,13 +1617,13 @@ called after stream is closed (see
 <a class="reference internal" href="#c.nghttp2_on_stream_close_callback" title="nghttp2_on_stream_close_callback"><tt class="xref c c-type docutils literal"><span class="pre">nghttp2_on_stream_close_callback</span></tt></a>).  The application should
 check that stream is still alive using its own stream management or
 <a class="reference internal" href="#c.nghttp2_session_get_stream_user_data" title="nghttp2_session_get_stream_user_data"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_get_stream_user_data()</span></tt></a>.</p>
-<p>Only HEADERS and DATA frame can signal the end of incoming data. If
+<p>Only HEADERS and DATA frame can signal the end of incoming data.
-<tt class="docutils literal"><span class="pre">frame-&gt;hd.flags</span> <span class="pre">&amp;</span> <span class="pre">NGHTTP2_FLAG_END_STREAM</span></tt> is nonzero, the
+If <tt class="docutils literal"><span class="pre">frame-&gt;hd.flags</span> <span class="pre">&amp;</span> <span class="pre">NGHTTP2_FLAG_END_STREAM</span></tt> is nonzero, the
 <em>frame</em> is the last frame from the remote peer in this stream.</p>
-<p>The implementation of this function must return 0 if it
+<p>The implementation of this function must return 0 if it succeeds.
-succeeds. If nonzero value is returned, it is treated as fatal
+If nonzero value is returned, it is treated as fatal error and
-error and <a class="reference internal" href="#c.nghttp2_session_recv" title="nghttp2_session_recv"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_recv()</span></tt></a> and <a class="reference internal" href="#c.nghttp2_session_mem_recv" title="nghttp2_session_mem_recv"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_mem_recv()</span></tt></a>
+<a class="reference internal" href="#c.nghttp2_session_recv" title="nghttp2_session_recv"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_recv()</span></tt></a> and <a class="reference internal" href="#c.nghttp2_session_mem_recv" title="nghttp2_session_mem_recv"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_mem_recv()</span></tt></a> functions
-functions immediately return <a class="reference internal" href="#c.NGHTTP2_ERR_CALLBACK_FAILURE" title="NGHTTP2_ERR_CALLBACK_FAILURE"><tt class="xref c c-macro docutils literal"><span class="pre">NGHTTP2_ERR_CALLBACK_FAILURE</span></tt></a>.</p>
+immediately return <a class="reference internal" href="#c.NGHTTP2_ERR_CALLBACK_FAILURE" title="NGHTTP2_ERR_CALLBACK_FAILURE"><tt class="xref c c-macro docutils literal"><span class="pre">NGHTTP2_ERR_CALLBACK_FAILURE</span></tt></a>.</p>
 </dd></dl>
 
 <dl class="type">
@@ -1636,8 +1639,8 @@ third argument passed in to the call to
 <p>If frame is HEADERS or PUSH_PROMISE, the <tt class="docutils literal"><span class="pre">nva</span></tt> and <tt class="docutils literal"><span class="pre">nvlen</span></tt>
 member of their data structure are always <tt class="docutils literal"><span class="pre">NULL</span></tt> and 0
 respectively.</p>
-<p>The implementation of this function must return 0 if it
+<p>The implementation of this function must return 0 if it succeeds.
-succeeds. If nonzero is returned, it is treated as fatal error and
+If nonzero is returned, it is treated as fatal error and
 <a class="reference internal" href="#c.nghttp2_session_recv" title="nghttp2_session_recv"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_recv()</span></tt></a> and <a class="reference internal" href="#c.nghttp2_session_send" title="nghttp2_session_send"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_send()</span></tt></a> functions
 immediately return <a class="reference internal" href="#c.NGHTTP2_ERR_CALLBACK_FAILURE" title="NGHTTP2_ERR_CALLBACK_FAILURE"><tt class="xref c c-macro docutils literal"><span class="pre">NGHTTP2_ERR_CALLBACK_FAILURE</span></tt></a>.</p>
 </dd></dl>
@@ -1647,23 +1650,23 @@ immediately return <a class="reference internal" href="#c.NGHTTP2_ERR_CALLBACK_F
 typedef int <tt class="descname">(*nghttp2_on_data_chunk_recv_callback)</tt><big>(</big><a class="reference internal" href="#c.nghttp2_session" title="nghttp2_session">nghttp2_session</a><em>&nbsp;*session</em>, uint8_t<em>&nbsp;flags</em>, int32_t<em>&nbsp;stream_id</em>, const uint8_t<em>&nbsp;*data</em>, size_t<em>&nbsp;len</em>, void<em>&nbsp;*user_data</em><big>)</big><a class="headerlink" href="#c.nghttp2_on_data_chunk_recv_callback" title="Permalink to this definition">¶</a></dt>
 <dd><p>Callback function invoked when a chunk of data in DATA frame is
 received.  The <em>stream_id</em> is the stream ID this DATA frame belongs
-to. The <em>flags</em> is the flags of DATA frame which this data chunk is
+to.  The <em>flags</em> is the flags of DATA frame which this data chunk
-contained. <tt class="docutils literal"><span class="pre">(flags</span> <span class="pre">&amp;</span> <span class="pre">NGHTTP2_FLAG_END_STREAM)</span> <span class="pre">!=</span> <span class="pre">0</span></tt> does not
+is contained.  <tt class="docutils literal"><span class="pre">(flags</span> <span class="pre">&amp;</span> <span class="pre">NGHTTP2_FLAG_END_STREAM)</span> <span class="pre">!=</span> <span class="pre">0</span></tt> does not
-necessarily mean this chunk of data is the last one in the
+necessarily mean this chunk of data is the last one in the stream.
-stream. You should use <a class="reference internal" href="#c.nghttp2_on_frame_recv_callback" title="nghttp2_on_frame_recv_callback"><tt class="xref c c-type docutils literal"><span class="pre">nghttp2_on_frame_recv_callback</span></tt></a> to
+You should use <a class="reference internal" href="#c.nghttp2_on_frame_recv_callback" title="nghttp2_on_frame_recv_callback"><tt class="xref c c-type docutils literal"><span class="pre">nghttp2_on_frame_recv_callback</span></tt></a> to know all
-know all data frames are received. The <em>user_data</em> pointer is the
+data frames are received.  The <em>user_data</em> pointer is the third
-third argument passed in to the call to
+argument passed in to the call to <a class="reference internal" href="#c.nghttp2_session_client_new" title="nghttp2_session_client_new"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_client_new()</span></tt></a> or
-<a class="reference internal" href="#c.nghttp2_session_client_new" title="nghttp2_session_client_new"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_client_new()</span></tt></a> or <a class="reference internal" href="#c.nghttp2_session_server_new" title="nghttp2_session_server_new"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_server_new()</span></tt></a>.</p>
+<a class="reference internal" href="#c.nghttp2_session_server_new" title="nghttp2_session_server_new"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_server_new()</span></tt></a>.</p>
 <p>If the application uses <a class="reference internal" href="#c.nghttp2_session_mem_recv" title="nghttp2_session_mem_recv"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_mem_recv()</span></tt></a>, it can return
 <a class="reference internal" href="#c.NGHTTP2_ERR_PAUSE" title="NGHTTP2_ERR_PAUSE"><tt class="xref c c-macro docutils literal"><span class="pre">NGHTTP2_ERR_PAUSE</span></tt></a> to make <a class="reference internal" href="#c.nghttp2_session_mem_recv" title="nghttp2_session_mem_recv"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_mem_recv()</span></tt></a>
 return without processing further input bytes.  The memory by
 pointed by the <em>data</em> is retained until
-<a class="reference internal" href="#c.nghttp2_session_mem_recv" title="nghttp2_session_mem_recv"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_mem_recv()</span></tt></a> or <a class="reference internal" href="#c.nghttp2_session_recv" title="nghttp2_session_recv"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_recv()</span></tt></a> is
+<a class="reference internal" href="#c.nghttp2_session_mem_recv" title="nghttp2_session_mem_recv"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_mem_recv()</span></tt></a> or <a class="reference internal" href="#c.nghttp2_session_recv" title="nghttp2_session_recv"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_recv()</span></tt></a> is called.
-called. The application must retain the input bytes which was used
+The application must retain the input bytes which was used to
-to produce the <em>data</em> parameter, because it may refer to the memory
+produce the <em>data</em> parameter, because it may refer to the memory
 region included in the input bytes.</p>
-<p>The implementation of this function must return 0 if it
+<p>The implementation of this function must return 0 if it succeeds.
-succeeds. If nonzero is returned, it is treated as fatal error and
+If nonzero is returned, it is treated as fatal error and
 <a class="reference internal" href="#c.nghttp2_session_recv" title="nghttp2_session_recv"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_recv()</span></tt></a> and <a class="reference internal" href="#c.nghttp2_session_mem_recv" title="nghttp2_session_mem_recv"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_mem_recv()</span></tt></a> functions
 immediately return <a class="reference internal" href="#c.NGHTTP2_ERR_CALLBACK_FAILURE" title="NGHTTP2_ERR_CALLBACK_FAILURE"><tt class="xref c c-macro docutils literal"><span class="pre">NGHTTP2_ERR_CALLBACK_FAILURE</span></tt></a>.</p>
 </dd></dl>
@@ -1678,8 +1681,8 @@ HEADERS and PUSH_PROMISE frame (see also
 when it was queued.  The <em>user_data</em> pointer is the third argument
 passed in to the call to <a class="reference internal" href="#c.nghttp2_session_client_new" title="nghttp2_session_client_new"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_client_new()</span></tt></a> or
 <a class="reference internal" href="#c.nghttp2_session_server_new" title="nghttp2_session_server_new"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_server_new()</span></tt></a>.</p>
-<p>The implementation of this function must return 0 if it
+<p>The implementation of this function must return 0 if it succeeds.
-succeeds. If nonzero is returned, it is treated as fatal error and
+If nonzero is returned, it is treated as fatal error and
 <a class="reference internal" href="#c.nghttp2_session_recv" title="nghttp2_session_recv"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_recv()</span></tt></a> and <a class="reference internal" href="#c.nghttp2_session_send" title="nghttp2_session_send"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_send()</span></tt></a> functions
 immediately return <a class="reference internal" href="#c.NGHTTP2_ERR_CALLBACK_FAILURE" title="NGHTTP2_ERR_CALLBACK_FAILURE"><tt class="xref c c-macro docutils literal"><span class="pre">NGHTTP2_ERR_CALLBACK_FAILURE</span></tt></a>.</p>
 </dd></dl>
@@ -1690,8 +1693,8 @@ typedef int <tt class="descname">(*nghttp2_on_frame_send_callback)</tt><big>(</b
 <dd><p>Callback function invoked after the frame <em>frame</em> is sent.  The
 <em>user_data</em> pointer is the third argument passed in to the call to
 <a class="reference internal" href="#c.nghttp2_session_client_new" title="nghttp2_session_client_new"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_client_new()</span></tt></a> or <a class="reference internal" href="#c.nghttp2_session_server_new" title="nghttp2_session_server_new"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_server_new()</span></tt></a>.</p>
-<p>The implementation of this function must return 0 if it
+<p>The implementation of this function must return 0 if it succeeds.
-succeeds. If nonzero is returned, it is treated as fatal error and
+If nonzero is returned, it is treated as fatal error and
 <a class="reference internal" href="#c.nghttp2_session_recv" title="nghttp2_session_recv"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_recv()</span></tt></a> and <a class="reference internal" href="#c.nghttp2_session_send" title="nghttp2_session_send"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_send()</span></tt></a> functions
 immediately return <a class="reference internal" href="#c.NGHTTP2_ERR_CALLBACK_FAILURE" title="NGHTTP2_ERR_CALLBACK_FAILURE"><tt class="xref c c-macro docutils literal"><span class="pre">NGHTTP2_ERR_CALLBACK_FAILURE</span></tt></a>.</p>
 </dd></dl>
@@ -1705,8 +1708,8 @@ sent because of the error. The error is indicated by the
 <a class="reference internal" href="#c.nghttp2_error" title="nghttp2_error"><tt class="xref c c-type docutils literal"><span class="pre">nghttp2_error</span></tt></a>.  The <em>user_data</em> pointer is the third
 argument passed in to the call to <a class="reference internal" href="#c.nghttp2_session_client_new" title="nghttp2_session_client_new"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_client_new()</span></tt></a> or
 <a class="reference internal" href="#c.nghttp2_session_server_new" title="nghttp2_session_server_new"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_server_new()</span></tt></a>.</p>
-<p>The implementation of this function must return 0 if it
+<p>The implementation of this function must return 0 if it succeeds.
-succeeds. If nonzero is returned, it is treated as fatal error and
+If nonzero is returned, it is treated as fatal error and
 <a class="reference internal" href="#c.nghttp2_session_recv" title="nghttp2_session_recv"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_recv()</span></tt></a> and <a class="reference internal" href="#c.nghttp2_session_send" title="nghttp2_session_send"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_send()</span></tt></a> functions
 immediately return <a class="reference internal" href="#c.NGHTTP2_ERR_CALLBACK_FAILURE" title="NGHTTP2_ERR_CALLBACK_FAILURE"><tt class="xref c c-macro docutils literal"><span class="pre">NGHTTP2_ERR_CALLBACK_FAILURE</span></tt></a>.</p>
 </dd></dl>
@@ -1714,15 +1717,16 @@ immediately return <a class="reference internal" href="#c.NGHTTP2_ERR_CALLBACK_F
 <dl class="type">
 <dt id="c.nghttp2_on_stream_close_callback">
 typedef int <tt class="descname">(*nghttp2_on_stream_close_callback)</tt><big>(</big><a class="reference internal" href="#c.nghttp2_session" title="nghttp2_session">nghttp2_session</a><em>&nbsp;*session</em>, int32_t<em>&nbsp;stream_id</em>, <a class="reference internal" href="#c.nghttp2_error_code" title="nghttp2_error_code">nghttp2_error_code</a><em>&nbsp;error_code</em>, void<em>&nbsp;*user_data</em><big>)</big><a class="headerlink" href="#c.nghttp2_on_stream_close_callback" title="Permalink to this definition">¶</a></dt>
-<dd><p>Callback function invoked when the stream <em>stream_id</em> is
+<dd><p>Callback function invoked when the stream <em>stream_id</em> is closed.
-closed. The reason of closure is indicated by the <em>error_code</em>. The
+The reason of closure is indicated by the <em>error_code</em>.  The
 stream_user_data, which was specified in <a class="reference internal" href="#c.nghttp2_submit_request" title="nghttp2_submit_request"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_submit_request()</span></tt></a>
-or <a class="reference internal" href="#c.nghttp2_submit_headers" title="nghttp2_submit_headers"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_submit_headers()</span></tt></a>, is still available in this
+or <a class="reference internal" href="#c.nghttp2_submit_headers" title="nghttp2_submit_headers"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_submit_headers()</span></tt></a>, is still available in this function.
-function. The <em>user_data</em> pointer is the third argument passed in
+The <em>user_data</em> pointer is the third argument passed in to the call
-to the call to <a class="reference internal" href="#c.nghttp2_session_client_new" title="nghttp2_session_client_new"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_client_new()</span></tt></a> or
+to <a class="reference internal" href="#c.nghttp2_session_client_new" title="nghttp2_session_client_new"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_client_new()</span></tt></a> or
 <a class="reference internal" href="#c.nghttp2_session_server_new" title="nghttp2_session_server_new"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_server_new()</span></tt></a>.</p>
-<p>The implementation of this function must return 0 if it
+<p>This function is also called for a stream in reserved state.</p>
-succeeds. If nonzero is returned, it is treated as fatal error and
+<p>The implementation of this function must return 0 if it succeeds.
+If nonzero is returned, it is treated as fatal error and
 <a class="reference internal" href="#c.nghttp2_session_recv" title="nghttp2_session_recv"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_recv()</span></tt></a> and <a class="reference internal" href="#c.nghttp2_session_send" title="nghttp2_session_send"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_send()</span></tt></a> functions
 immediately return <a class="reference internal" href="#c.NGHTTP2_ERR_CALLBACK_FAILURE" title="NGHTTP2_ERR_CALLBACK_FAILURE"><tt class="xref c c-macro docutils literal"><span class="pre">NGHTTP2_ERR_CALLBACK_FAILURE</span></tt></a>.</p>
 </dd></dl>
@@ -1730,18 +1734,17 @@ immediately return <a class="reference internal" href="#c.NGHTTP2_ERR_CALLBACK_F
 <dl class="type">
 <dt id="c.nghttp2_on_unknown_frame_recv_callback">
 typedef int <tt class="descname">(*nghttp2_on_unknown_frame_recv_callback)</tt><big>(</big><a class="reference internal" href="#c.nghttp2_session" title="nghttp2_session">nghttp2_session</a><em>&nbsp;*session</em>, const uint8_t<em>&nbsp;*head</em>, size_t<em>&nbsp;headlen</em>, const uint8_t<em>&nbsp;*payload</em>, size_t<em>&nbsp;payloadlen</em>, void<em>&nbsp;*user_data</em><big>)</big><a class="headerlink" href="#c.nghttp2_on_unknown_frame_recv_callback" title="Permalink to this definition">¶</a></dt>
-<dd><p>Callback function invoked when the received frame type is
+<dd><p>Callback function invoked when the received frame type is unknown.
-unknown. The <em>head</em> is the pointer to the header of the received
+The <em>head</em> is the pointer to the header of the received frame.  The
-frame. The <em>headlen</em> is the length of the <em>head</em>. According to the
+<em>headlen</em> is the length of the <em>head</em>.  According to the spec, the
-spec, the <em>headlen</em> is always 8. In other words, the <em>head</em> is the
+<em>headlen</em> is always 8.  In other words, the <em>head</em> is the first 8
-first 8 bytes of the received frame.  The <em>payload</em> is the pointer
+bytes of the received frame.  The <em>payload</em> is the pointer to the
-to the data portion of the received frame.  The <em>payloadlen</em> is the
+data portion of the received frame.  The <em>payloadlen</em> is the length
-length of the <em>payload</em>. This is the data after the length
+of the <em>payload</em>.  This is the data after the length field.  The
-field. The <em>user_data</em> pointer is the third argument passed in to
+<em>user_data</em> pointer is the third argument passed in to the call to
-the call to <a class="reference internal" href="#c.nghttp2_session_client_new" title="nghttp2_session_client_new"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_client_new()</span></tt></a> or
+<a class="reference internal" href="#c.nghttp2_session_client_new" title="nghttp2_session_client_new"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_client_new()</span></tt></a> or <a class="reference internal" href="#c.nghttp2_session_server_new" title="nghttp2_session_server_new"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_server_new()</span></tt></a>.</p>
-<a class="reference internal" href="#c.nghttp2_session_server_new" title="nghttp2_session_server_new"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_server_new()</span></tt></a>.</p>
+<p>The implementation of this function must return 0 if it succeeds.
-<p>The implementation of this function must return 0 if it
+If nonzero is returned, it is treated as fatal error and
-succeeds. If nonzero is returned, it is treated as fatal error and
 <a class="reference internal" href="#c.nghttp2_session_recv" title="nghttp2_session_recv"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_recv()</span></tt></a> and <a class="reference internal" href="#c.nghttp2_session_send" title="nghttp2_session_send"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_send()</span></tt></a> functions
 immediately return <a class="reference internal" href="#c.NGHTTP2_ERR_CALLBACK_FAILURE" title="NGHTTP2_ERR_CALLBACK_FAILURE"><tt class="xref c c-macro docutils literal"><span class="pre">NGHTTP2_ERR_CALLBACK_FAILURE</span></tt></a>.</p>
 </dd></dl>
@@ -1801,16 +1804,16 @@ concatenation is used in order to keep the ordering of headers.</p>
 <a class="reference internal" href="#c.NGHTTP2_ERR_PAUSE" title="NGHTTP2_ERR_PAUSE"><tt class="xref c c-macro docutils literal"><span class="pre">NGHTTP2_ERR_PAUSE</span></tt></a> to make <a class="reference internal" href="#c.nghttp2_session_mem_recv" title="nghttp2_session_mem_recv"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_mem_recv()</span></tt></a>
 return without processing further input bytes.  The memory pointed
 by <em>frame</em>, <em>name</em> and <em>value</em> parameters are retained until
-<a class="reference internal" href="#c.nghttp2_session_mem_recv" title="nghttp2_session_mem_recv"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_mem_recv()</span></tt></a> or <a class="reference internal" href="#c.nghttp2_session_recv" title="nghttp2_session_recv"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_recv()</span></tt></a> is
+<a class="reference internal" href="#c.nghttp2_session_mem_recv" title="nghttp2_session_mem_recv"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_mem_recv()</span></tt></a> or <a class="reference internal" href="#c.nghttp2_session_recv" title="nghttp2_session_recv"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_recv()</span></tt></a> is called.
-called. The application must retain the input bytes which was used
+The application must retain the input bytes which was used to
-to produce these parameters, because it may refer to the memory
+produce these parameters, because it may refer to the memory region
-region included in the input bytes.</p>
+included in the input bytes.</p>
 <p>Returning <a class="reference internal" href="#c.NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE" title="NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE"><tt class="xref c c-macro docutils literal"><span class="pre">NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE</span></tt></a> will close
 the stream by issuing RST_STREAM with
 <a class="reference internal" href="#c.NGHTTP2_INTERNAL_ERROR" title="NGHTTP2_INTERNAL_ERROR"><tt class="xref c c-macro docutils literal"><span class="pre">NGHTTP2_INTERNAL_ERROR</span></tt></a>.  In this case,
 <a class="reference internal" href="#c.nghttp2_on_frame_recv_callback" title="nghttp2_on_frame_recv_callback"><tt class="xref c c-type docutils literal"><span class="pre">nghttp2_on_frame_recv_callback</span></tt></a> will not be invoked.</p>
-<p>The implementation of this function must return 0 if it
+<p>The implementation of this function must return 0 if it succeeds.
-succeeds. It may return <a class="reference internal" href="#c.NGHTTP2_ERR_PAUSE" title="NGHTTP2_ERR_PAUSE"><tt class="xref c c-macro docutils literal"><span class="pre">NGHTTP2_ERR_PAUSE</span></tt></a> or
+It may return <a class="reference internal" href="#c.NGHTTP2_ERR_PAUSE" title="NGHTTP2_ERR_PAUSE"><tt class="xref c c-macro docutils literal"><span class="pre">NGHTTP2_ERR_PAUSE</span></tt></a> or
 <a class="reference internal" href="#c.NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE" title="NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE"><tt class="xref c c-macro docutils literal"><span class="pre">NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE</span></tt></a>.  For other critical
 failures, it must return <a class="reference internal" href="#c.NGHTTP2_ERR_CALLBACK_FAILURE" title="NGHTTP2_ERR_CALLBACK_FAILURE"><tt class="xref c c-macro docutils literal"><span class="pre">NGHTTP2_ERR_CALLBACK_FAILURE</span></tt></a>.  If
 the other nonzero value is returned, it is treated as
@@ -1824,9 +1827,9 @@ immediately return <a class="reference internal" href="#c.NGHTTP2_ERR_CALLBACK_F
 <dt id="c.nghttp2_select_padding_callback">
 typedef ssize_t <tt class="descname">(*nghttp2_select_padding_callback)</tt><big>(</big><a class="reference internal" href="#c.nghttp2_session" title="nghttp2_session">nghttp2_session</a><em>&nbsp;*session</em>, const <a class="reference internal" href="#c.nghttp2_frame" title="nghttp2_frame">nghttp2_frame</a><em>&nbsp;*frame</em>, size_t<em>&nbsp;max_payloadlen</em>, void<em>&nbsp;*user_data</em><big>)</big><a class="headerlink" href="#c.nghttp2_select_padding_callback" title="Permalink to this definition">¶</a></dt>
 <dd><p>Callback function invoked when the library asks application how
-much padding is required for the transmission of the <em>frame</em>. The
+many padding bytes are required for the transmission of the
-application must choose the total length of payload including
+<em>frame</em>.  The application must choose the total length of payload
-padded bytes in range [frame-&gt;hd.length, max_payloadlen],
+including padded bytes in range [frame-&gt;hd.length, max_payloadlen],
 inclusive.  Choosing number not in this range will be treated as
 <a class="reference internal" href="#c.NGHTTP2_ERR_CALLBACK_FAILURE" title="NGHTTP2_ERR_CALLBACK_FAILURE"><tt class="xref c c-macro docutils literal"><span class="pre">NGHTTP2_ERR_CALLBACK_FAILURE</span></tt></a>.  Returning
 <tt class="docutils literal"><span class="pre">frame-&gt;hd.length</span></tt> means no padding is added.  Returning
@@ -1844,8 +1847,8 @@ inclusive. Choosing number not in this range will be treated as
 <a class="reference internal" href="#c.nghttp2_send_callback" title="nghttp2_send_callback">nghttp2_send_callback</a> <tt class="descname">send_callback</tt><a class="headerlink" href="#c.nghttp2_session_callbacks.send_callback" title="Permalink to this definition">¶</a></dt>
 <dd><p>Callback function invoked when the <em>session</em> wants to send data
 to the remote peer.  This callback is not necessary if the
-application uses <a class="reference internal" href="#c.nghttp2_session_mem_send" title="nghttp2_session_mem_send"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_mem_send()</span></tt></a> to serialize data
+application uses solely <a class="reference internal" href="#c.nghttp2_session_mem_send" title="nghttp2_session_mem_send"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_mem_send()</span></tt></a> to serialize
-to transmit.</p>
+data to transmit.</p>
 </dd></dl>
 
 <dl class="member">
@@ -1853,8 +1856,8 @@ to transmit.</p>
 <a class="reference internal" href="#c.nghttp2_recv_callback" title="nghttp2_recv_callback">nghttp2_recv_callback</a> <tt class="descname">recv_callback</tt><a class="headerlink" href="#c.nghttp2_session_callbacks.recv_callback" title="Permalink to this definition">¶</a></dt>
 <dd><p>Callback function invoked when the <em>session</em> wants to receive
 data from the remote peer.  This callback is not necessary if the
-application uses <a class="reference internal" href="#c.nghttp2_session_mem_recv" title="nghttp2_session_mem_recv"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_mem_recv()</span></tt></a> to process received
+application uses solely <a class="reference internal" href="#c.nghttp2_session_mem_recv" title="nghttp2_session_mem_recv"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_mem_recv()</span></tt></a> to process
-data.</p>
+received data.</p>
 </dd></dl>
 
 <dl class="member">
@@ -1928,7 +1931,8 @@ received.</p>
 <dt id="c.nghttp2_session_callbacks.select_padding_callback">
 <a class="reference internal" href="#c.nghttp2_select_padding_callback" title="nghttp2_select_padding_callback">nghttp2_select_padding_callback</a> <tt class="descname">select_padding_callback</tt><a class="headerlink" href="#c.nghttp2_session_callbacks.select_padding_callback" title="Permalink to this definition">¶</a></dt>
 <dd><p>Callback function invoked when the library asks application how
-much padding is required for the transmission of the given frame.</p>
+many padding bytes are required for the transmission of the given
+frame.</p>
 </dd></dl>
 
 </dd></dl>
@@ -1988,9 +1992,9 @@ void <tt class="descname">nghttp2_option_set_no_auto_connection_window_update</t
 <dd><p>This option prevents the library from sending WINDOW_UPDATE for a
 connection automatically.  If this option is set to nonzero, the
 library won&#8217;t send WINDOW_UPDATE for a connection and the
-application is responsible for sending WINDOW_UPDATE with stream
+application is responsible for sending WINDOW_UPDATE with stream ID
-ID 0 using <a class="reference internal" href="#c.nghttp2_submit_window_update" title="nghttp2_submit_window_update"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_submit_window_update()</span></tt></a>. By default, this
+0 using <a class="reference internal" href="#c.nghttp2_submit_window_update" title="nghttp2_submit_window_update"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_submit_window_update()</span></tt></a>.  By default, this option is
-option is set to zero.</p>
+set to zero.</p>
 </dd></dl>
 
 <dl class="function">
@@ -2001,11 +2005,11 @@ remote endpoint as if it is received in SETTINGS frame. Without
 specifying this option, before the local endpoint receives
 SETTINGS_MAX_CONCURRENT_STREAMS in SETTINGS frame from remote
 endpoint, SETTINGS_MAX_CONCURRENT_STREAMS is unlimited.  This may
-cause problem if local endpoint submits lots of requests
+cause problem if local endpoint submits lots of requests initially
-initially and sending them at once to the remote peer may lead to
+and sending them at once to the remote peer may lead to the
-the rejection of some requests. Specifying this option to the
+rejection of some requests.  Specifying this option to the sensible
-sensible value, say 100, may avoid this kind of issue. This value
+value, say 100, may avoid this kind of issue. This value will be
-will be overwritten if the local endpoint receives
+overwritten if the local endpoint receives
 SETTINGS_MAX_CONCURRENT_STREAMS from the remote endpoint.</p>
 </dd></dl>
 
@@ -2014,7 +2018,7 @@ SETTINGS_MAX_CONCURRENT_STREAMS from the remote endpoint.</p>
 int <tt class="descname">nghttp2_session_client_new</tt><big>(</big><a class="reference internal" href="#c.nghttp2_session" title="nghttp2_session">nghttp2_session</a><em>&nbsp;**session_ptr</em>, const <a class="reference internal" href="#c.nghttp2_session_callbacks" title="nghttp2_session_callbacks">nghttp2_session_callbacks</a><em>&nbsp;*callbacks</em>, void<em>&nbsp;*user_data</em><big>)</big><a class="headerlink" href="#c.nghttp2_session_client_new" title="Permalink to this definition">¶</a></dt>
 <dd><p>Initializes <em>*session_ptr</em> for client use.  The all members of
 <em>callbacks</em> are copied to <em>*session_ptr</em>.  Therefore <em>*session_ptr</em>
-does not store <em>callbacks</em>. <em>user_data</em> is an arbitrary user
+does not store <em>callbacks</em>.  The <em>user_data</em> is an arbitrary user
 supplied data, which will be passed to the callback functions.</p>
 <p>The <a class="reference internal" href="#c.nghttp2_session_callbacks.send_callback" title="nghttp2_session_callbacks.send_callback"><tt class="xref c c-member docutils literal"><span class="pre">nghttp2_session_callbacks.send_callback</span></tt></a> must be
 specified.  If the application code uses <a class="reference internal" href="#c.nghttp2_session_recv" title="nghttp2_session_recv"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_recv()</span></tt></a>,
@@ -2033,7 +2037,7 @@ negative error codes:</p>
 int <tt class="descname">nghttp2_session_server_new</tt><big>(</big><a class="reference internal" href="#c.nghttp2_session" title="nghttp2_session">nghttp2_session</a><em>&nbsp;**session_ptr</em>, const <a class="reference internal" href="#c.nghttp2_session_callbacks" title="nghttp2_session_callbacks">nghttp2_session_callbacks</a><em>&nbsp;*callbacks</em>, void<em>&nbsp;*user_data</em><big>)</big><a class="headerlink" href="#c.nghttp2_session_server_new" title="Permalink to this definition">¶</a></dt>
 <dd><p>Initializes <em>*session_ptr</em> for server use.  The all members of
 <em>callbacks</em> are copied to <em>*session_ptr</em>. Therefore <em>*session_ptr</em>
-does not store <em>callbacks</em>. <em>user_data</em> is an arbitrary user
+does not store <em>callbacks</em>.  The <em>user_data</em> is an arbitrary user
 supplied data, which will be passed to the callback functions.</p>
 <p>The <a class="reference internal" href="#c.nghttp2_session_callbacks.send_callback" title="nghttp2_session_callbacks.send_callback"><tt class="xref c c-member docutils literal"><span class="pre">nghttp2_session_callbacks.send_callback</span></tt></a> must be
 specified.  If the application code uses <a class="reference internal" href="#c.nghttp2_session_recv" title="nghttp2_session_recv"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_recv()</span></tt></a>,
@@ -2108,12 +2112,13 @@ which tells when each callback is invoked:</p>
 <li>Get the next frame to send from outbound queue.</li>
 <li>Prepare transmission of the frame.</li>
 <li>If the control frame cannot be sent because some preconditions
-are not met (e.g., request HEADERS cannot be sent after
+are not met (e.g., request HEADERS cannot be sent after GOAWAY),
-GOAWAY),
+<a class="reference internal" href="#c.nghttp2_session_callbacks.on_frame_not_send_callback" title="nghttp2_session_callbacks.on_frame_not_send_callback"><tt class="xref c c-member docutils literal"><span class="pre">nghttp2_session_callbacks.on_frame_not_send_callback</span></tt></a>
-<a class="reference internal" href="#c.nghttp2_session_callbacks.on_frame_not_send_callback" title="nghttp2_session_callbacks.on_frame_not_send_callback"><tt class="xref c c-member docutils literal"><span class="pre">nghttp2_session_callbacks.on_frame_not_send_callback</span></tt></a> is
+is invoked.  Abort the following steps.</li>
-invoked. Abort the following steps.</li>
+<li>If the frame is HEADERS, PUSH_PROMISE or DATA,
-<li>If the frame is request HEADERS, the stream is opened
+<a class="reference internal" href="#c.nghttp2_session_callbacks.select_padding_callback" title="nghttp2_session_callbacks.select_padding_callback"><tt class="xref c c-member docutils literal"><span class="pre">nghttp2_session_callbacks.select_padding_callback</span></tt></a> is
-here.</li>
+invoked.</li>
+<li>If the frame is request HEADERS, the stream is opened here.</li>
 <li><a class="reference internal" href="#c.nghttp2_session_callbacks.before_frame_send_callback" title="nghttp2_session_callbacks.before_frame_send_callback"><tt class="xref c c-member docutils literal"><span class="pre">nghttp2_session_callbacks.before_frame_send_callback</span></tt></a> is
 invoked.</li>
 <li><a class="reference internal" href="#c.nghttp2_session_callbacks.send_callback" title="nghttp2_session_callbacks.send_callback"><tt class="xref c c-member docutils literal"><span class="pre">nghttp2_session_callbacks.send_callback</span></tt></a> is invoked one
@@ -2139,15 +2144,16 @@ negative error codes:</p>
 <dt id="c.nghttp2_session_mem_send">
 ssize_t <tt class="descname">nghttp2_session_mem_send</tt><big>(</big><a class="reference internal" href="#c.nghttp2_session" title="nghttp2_session">nghttp2_session</a><em>&nbsp;*session</em>, const uint8_t<em>&nbsp;**data_ptr</em><big>)</big><a class="headerlink" href="#c.nghttp2_session_mem_send" title="Permalink to this definition">¶</a></dt>
 <dd><p>Returns the serialized data to send.</p>
-<p>This function behaves like <a class="reference internal" href="#c.nghttp2_session_send" title="nghttp2_session_send"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_send()</span></tt></a> except that
+<p>This function behaves like <a class="reference internal" href="#c.nghttp2_session_send" title="nghttp2_session_send"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_send()</span></tt></a> except that it
-it does not use <a class="reference internal" href="#c.nghttp2_session_callbacks.send_callback" title="nghttp2_session_callbacks.send_callback"><tt class="xref c c-member docutils literal"><span class="pre">nghttp2_session_callbacks.send_callback</span></tt></a>
+does not use <a class="reference internal" href="#c.nghttp2_session_callbacks.send_callback" title="nghttp2_session_callbacks.send_callback"><tt class="xref c c-member docutils literal"><span class="pre">nghttp2_session_callbacks.send_callback</span></tt></a> to
-to transmit data. Instead, it assigns the pointer to the serialized
+transmit data.  Instead, it assigns the pointer to the serialized
-data to the <em>*data_ptr</em> and returns its length. The other callbacks
+data to the <em>*data_ptr</em> and returns its length.  The other
-are called in the same way as they are in <a class="reference internal" href="#c.nghttp2_session_send" title="nghttp2_session_send"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_send()</span></tt></a>.</p>
+callbacks are called in the same way as they are in
+<a class="reference internal" href="#c.nghttp2_session_send" title="nghttp2_session_send"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_send()</span></tt></a>.</p>
 <p>If no data is available to send, this function returns 0.</p>
-<p>This function may not return all serialized data in one
+<p>This function may not return all serialized data in one invocation.
-invocation. To get all data, call this function repeatedly until it
+To get all data, call this function repeatedly until it returns 0
-returns 0 or one of negative error codes.</p>
+or one of negative error codes.</p>
 <p>The assigned <em>*data_ptr</em> is valid until the next call of
 <a class="reference internal" href="#c.nghttp2_session_mem_send" title="nghttp2_session_mem_send"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_mem_send()</span></tt></a> or <a class="reference internal" href="#c.nghttp2_session_send" title="nghttp2_session_send"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_send()</span></tt></a>.</p>
 <p>The caller must send all data before sending the next chunk of
@@ -2309,8 +2315,8 @@ initiated by the remote endpoint, stream_user_data is always
 <dt id="c.nghttp2_session_set_stream_user_data">
 int <tt class="descname">nghttp2_session_set_stream_user_data</tt><big>(</big><a class="reference internal" href="#c.nghttp2_session" title="nghttp2_session">nghttp2_session</a><em>&nbsp;*session</em>, int32_t<em>&nbsp;stream_id</em>, void<em>&nbsp;*stream_user_data</em><big>)</big><a class="headerlink" href="#c.nghttp2_session_set_stream_user_data" title="Permalink to this definition">¶</a></dt>
 <dd><p>Sets the <em>stream_user_data</em> to the stream denoted by the
-<em>stream_id</em>. If a stream user data is already set to the stream, it
+<em>stream_id</em>.  If a stream user data is already set to the stream,
-is replaced with the <em>stream_user_data</em>. It is valid to specify
+it is replaced with the <em>stream_user_data</em>.  It is valid to specify
 <tt class="docutils literal"><span class="pre">NULL</span></tt> in the <em>stream_user_data</em>, which nullifies the associated
 data pointer.</p>
 <p>It is valid to set the <em>stream_user_data</em> to the stream reserved by
@@ -2347,8 +2353,8 @@ function returns the number of bytes less than actually received.</p>
 <dl class="function">
 <dt id="c.nghttp2_session_get_stream_effective_local_window_size">
 int32_t <tt class="descname">nghttp2_session_get_stream_effective_local_window_size</tt><big>(</big><a class="reference internal" href="#c.nghttp2_session" title="nghttp2_session">nghttp2_session</a><em>&nbsp;*session</em>, int32_t<em>&nbsp;stream_id</em><big>)</big><a class="headerlink" href="#c.nghttp2_session_get_stream_effective_local_window_size" title="Permalink to this definition">¶</a></dt>
-<dd><p>Returns the local (receive) window size for the stream
+<dd><p>Returns the local (receive) window size for the stream <em>stream_id</em>.
-<em>stream_id</em>. The local window size can be adjusted by
+The local window size can be adjusted by
 <a class="reference internal" href="#c.nghttp2_submit_window_update" title="nghttp2_submit_window_update"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_submit_window_update()</span></tt></a>.  This function takes into account
 that and returns effective window size.</p>
 <p>This function returns -1 if it fails.</p>
@@ -2359,20 +2365,20 @@ that and returns effective window size.</p>
 int32_t <tt class="descname">nghttp2_session_get_effective_recv_data_length</tt><big>(</big><a class="reference internal" href="#c.nghttp2_session" title="nghttp2_session">nghttp2_session</a><em>&nbsp;*session</em><big>)</big><a class="headerlink" href="#c.nghttp2_session_get_effective_recv_data_length" title="Permalink to this definition">¶</a></dt>
 <dd><p>Returns the number of DATA payload in bytes received without
 WINDOW_UPDATE transmission for a connection.  The local (receive)
-window size can be adjusted by
+window size can be adjusted by <a class="reference internal" href="#c.nghttp2_submit_window_update" title="nghttp2_submit_window_update"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_submit_window_update()</span></tt></a>.
-<a class="reference internal" href="#c.nghttp2_submit_window_update" title="nghttp2_submit_window_update"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_submit_window_update()</span></tt></a>. This function takes into account
+This function takes into account that and returns effective data
-that and returns effective data length. In particular, if the local
+length.  In particular, if the local window size is reduced by
-window size is reduced by submitting negative window_size_increment
+submitting negative window_size_increment with
-with <a class="reference internal" href="#c.nghttp2_submit_window_update" title="nghttp2_submit_window_update"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_submit_window_update()</span></tt></a>, this function returns the
+<a class="reference internal" href="#c.nghttp2_submit_window_update" title="nghttp2_submit_window_update"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_submit_window_update()</span></tt></a>, this function returns the number
-number of bytes less than actually received.</p>
+of bytes less than actually received.</p>
 <p>This function returns -1 if it fails.</p>
 </dd></dl>
 
 <dl class="function">
 <dt id="c.nghttp2_session_get_effective_local_window_size">
 int32_t <tt class="descname">nghttp2_session_get_effective_local_window_size</tt><big>(</big><a class="reference internal" href="#c.nghttp2_session" title="nghttp2_session">nghttp2_session</a><em>&nbsp;*session</em><big>)</big><a class="headerlink" href="#c.nghttp2_session_get_effective_local_window_size" title="Permalink to this definition">¶</a></dt>
-<dd><p>Returns the local (receive) window size for a connection. The local
+<dd><p>Returns the local (receive) window size for a connection.  The
-window size can be adjusted by
+local window size can be adjusted by
 <a class="reference internal" href="#c.nghttp2_submit_window_update" title="nghttp2_submit_window_update"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_submit_window_update()</span></tt></a>.  This function takes into account
 that and returns effective window size.</p>
 <p>This function returns -1 if it fails.</p>
@@ -2399,8 +2405,8 @@ this function is invoked, <a class="reference internal" href="#c.nghttp2_session
 <a class="reference internal" href="#c.nghttp2_session_want_write" title="nghttp2_session_want_write"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_want_write()</span></tt></a> returns 0 immediately after this
 function succeeds.</p>
 <p>This function should be called when the connection should be
-terminated after sending GOAWAY. If the remaining streams should be
+terminated after sending GOAWAY.  If the remaining streams should
-processed after GOAWAY, use <a class="reference internal" href="#c.nghttp2_submit_goaway" title="nghttp2_submit_goaway"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_submit_goaway()</span></tt></a> instead.</p>
+be processed after GOAWAY, use <a class="reference internal" href="#c.nghttp2_submit_goaway" title="nghttp2_submit_goaway"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_submit_goaway()</span></tt></a> instead.</p>
 <p>This function returns 0 if it succeeds, or one of the following
 negative error codes:</p>
 <dl class="docutils">
@@ -2412,19 +2418,18 @@ negative error codes:</p>
 <dl class="function">
 <dt id="c.nghttp2_session_upgrade">
 int <tt class="descname">nghttp2_session_upgrade</tt><big>(</big><a class="reference internal" href="#c.nghttp2_session" title="nghttp2_session">nghttp2_session</a><em>&nbsp;*session</em>, const uint8_t<em>&nbsp;*settings_payload</em>, size_t<em>&nbsp;settings_payloadlen</em>, void<em>&nbsp;*stream_user_data</em><big>)</big><a class="headerlink" href="#c.nghttp2_session_upgrade" title="Permalink to this definition">¶</a></dt>
-<dd><p>Performs post-process of HTTP Upgrade request. This function can be
+<dd><p>Performs post-process of HTTP Upgrade request.  This function can
-called from both client and server, but the behavior is very
+be called from both client and server, but the behavior is very
 different in each other.</p>
 <p>If called from client side, the <em>settings_payload</em> must be the
 value sent in <tt class="docutils literal"><span class="pre">HTTP2-Settings</span></tt> header field and must be decoded
 by base64url decoder.  The <em>settings_payloadlen</em> is the length of
 <em>settings_payload</em>.  The <em>settings_payload</em> is unpacked and its
-setting values will be submitted using
+setting values will be submitted using <a class="reference internal" href="#c.nghttp2_submit_settings" title="nghttp2_submit_settings"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_submit_settings()</span></tt></a>.
-<a class="reference internal" href="#c.nghttp2_submit_settings" title="nghttp2_submit_settings"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_submit_settings()</span></tt></a>. This means that the client application
+This means that the client application code does not need to submit
-code does not need to submit SETTINGS by itself. The stream with
+SETTINGS by itself.  The stream with stream ID=1 is opened and the
-stream ID=1 is opened and the <em>stream_user_data</em> is used for its
+<em>stream_user_data</em> is used for its stream_user_data.  The opened
-stream_user_data. The opened stream becomes half-closed (local)
+stream becomes half-closed (local) state.</p>
-state.</p>
 <p>If called from server side, the <em>settings_payload</em> must be the
 value received in <tt class="docutils literal"><span class="pre">HTTP2-Settings</span></tt> header field and must be
 decoded by base64url decoder.  The <em>settings_payloadlen</em> is the
@@ -2533,8 +2538,8 @@ prioritized one first and the HTTP/2 specification requires the
 stream ID must be strictly increasing, the stream ID of this
 request cannot be known until it is about to sent.  To know the
 stream ID of the request, the application can use
-<a class="reference internal" href="#c.nghttp2_session_callbacks.before_frame_send_callback" title="nghttp2_session_callbacks.before_frame_send_callback"><tt class="xref c c-member docutils literal"><span class="pre">nghttp2_session_callbacks.before_frame_send_callback</span></tt></a>. This
+<a class="reference internal" href="#c.nghttp2_session_callbacks.before_frame_send_callback" title="nghttp2_session_callbacks.before_frame_send_callback"><tt class="xref c c-member docutils literal"><span class="pre">nghttp2_session_callbacks.before_frame_send_callback</span></tt></a>.
-callback is called just before the frame is sent. For HEADERS
+This callback is called just before the frame is sent.  For HEADERS
 frame, the argument frame has the stream ID assigned.  Also since
 the stream is already opened,
 <a class="reference internal" href="#c.nghttp2_session_get_stream_user_data" title="nghttp2_session_get_stream_user_data"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_get_stream_user_data()</span></tt></a> can be used to get
@@ -2544,6 +2549,8 @@ negative error codes:</p>
 <dl class="docutils">
 <dt><a class="reference internal" href="#c.NGHTTP2_ERR_NOMEM" title="NGHTTP2_ERR_NOMEM"><tt class="xref c c-macro docutils literal"><span class="pre">NGHTTP2_ERR_NOMEM</span></tt></a></dt>
 <dd>Out of memory.</dd>
+<dt><a class="reference internal" href="#c.NGHTTP2_ERR_INVALID_ARGUMENT" title="NGHTTP2_ERR_INVALID_ARGUMENT"><tt class="xref c c-macro docutils literal"><span class="pre">NGHTTP2_ERR_INVALID_ARGUMENT</span></tt></a></dt>
+<dd>The <em>pri_spec-&gt;pri_type</em> is invalid.</dd>
 </dl>
 </dd></dl>
 
@@ -2567,11 +2574,11 @@ in subsequent DATA frames.  This function does not take ownership
 of the <em>data_prd</em>.  The function copies the members of the
 <em>data_prd</em>.  If <em>data_prd</em> is <tt class="docutils literal"><span class="pre">NULL</span></tt>, HEADERS will have
 END_STREAM flag set.</p>
-<p>This method can be used as normal HTTP response and push
+<p>This method can be used as normal HTTP response and push response.
-response. When pushing a resource using this function, the
+When pushing a resource using this function, the <em>session</em> must be
-<em>session</em> must be configured using <a class="reference internal" href="#c.nghttp2_session_server_new" title="nghttp2_session_server_new"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_server_new()</span></tt></a>
+configured using <a class="reference internal" href="#c.nghttp2_session_server_new" title="nghttp2_session_server_new"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_session_server_new()</span></tt></a> or its variants and
-or its variants and the target stream denoted by the <em>stream_id</em>
+the target stream denoted by the <em>stream_id</em> must be reserved using
-must be reserved using <a class="reference internal" href="#c.nghttp2_submit_push_promise" title="nghttp2_submit_push_promise"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_submit_push_promise()</span></tt></a>.</p>
+<a class="reference internal" href="#c.nghttp2_submit_push_promise" title="nghttp2_submit_push_promise"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_submit_push_promise()</span></tt></a>.</p>
 <p>This function returns 0 if it succeeds, or one of the following
 negative error codes:</p>
 <dl class="docutils">
@@ -2612,9 +2619,9 @@ using NULL byte (0x0) before passing them to this function.</p>
 <p>This function creates copies of all name/value pairs in <em>nva</em>.  It
 also lower-cases all names in <em>nva</em>.</p>
 <p>The <em>stream_user_data</em> is a pointer to an arbitrary data which is
-associated to the stream this frame will open. Therefore it is only
+associated to the stream this frame will open.  Therefore it is
-used if this frame opens streams, in other words, it changes stream
+only used if this frame opens streams, in other words, it changes
-state from idle or reserved to open.</p>
+stream state from idle or reserved to open.</p>
 <p>This function is low-level in a sense that the application code can
 specify flags directly.  For usual HTTP request,
 <a class="reference internal" href="#c.nghttp2_submit_request" title="nghttp2_submit_request"><tt class="xref c c-func docutils literal"><span class="pre">nghttp2_submit_request()</span></tt></a> is useful.</p>
@@ -2623,6 +2630,8 @@ negative error codes:</p>
 <dl class="docutils">
 <dt><a class="reference internal" href="#c.NGHTTP2_ERR_NOMEM" title="NGHTTP2_ERR_NOMEM"><tt class="xref c c-macro docutils literal"><span class="pre">NGHTTP2_ERR_NOMEM</span></tt></a></dt>
 <dd>Out of memory.</dd>
+<dt><a class="reference internal" href="#c.NGHTTP2_ERR_INVALID_ARGUMENT" title="NGHTTP2_ERR_INVALID_ARGUMENT"><tt class="xref c c-macro docutils literal"><span class="pre">NGHTTP2_ERR_INVALID_ARGUMENT</span></tt></a></dt>
+<dd>The <em>pri_spec-&gt;pri_type</em> is invalid.</dd>
 </dl>
 </dd></dl>
 
@@ -2632,8 +2641,8 @@ int <tt class="descname">nghttp2_submit_data</tt><big>(</big><a class="reference
 <dd><p>Submits one or more DATA frames to the stream <em>stream_id</em>.  The
 data to be sent are provided by <em>data_prd</em>.  If <em>flags</em> contains
 <a class="reference internal" href="#c.NGHTTP2_FLAG_END_STREAM" title="NGHTTP2_FLAG_END_STREAM"><tt class="xref c c-macro docutils literal"><span class="pre">NGHTTP2_FLAG_END_STREAM</span></tt></a>, the last DATA frame has END_STREAM
-flag set. If <em>flags</em> contains <a class="reference internal" href="#c.NGHTTP2_FLAG_END_SEGMENT" title="NGHTTP2_FLAG_END_SEGMENT"><tt class="xref c c-macro docutils literal"><span class="pre">NGHTTP2_FLAG_END_SEGMENT</span></tt></a>, the
+flag set.  If <em>flags</em> contains <a class="reference internal" href="#c.NGHTTP2_FLAG_END_SEGMENT" title="NGHTTP2_FLAG_END_SEGMENT"><tt class="xref c c-macro docutils literal"><span class="pre">NGHTTP2_FLAG_END_SEGMENT</span></tt></a>,
-last DATA frame has END_SEGMENT flag set.</p>
+the last DATA frame has END_SEGMENT flag set.</p>
 <p>This function does not take ownership of the <em>data_prd</em>.  The
 function copies the members of the <em>data_prd</em>.</p>
 <p>This function returns 0 if it succeeds, or one of the following
@@ -2664,7 +2673,8 @@ negative error codes:</p>
 <dt><a class="reference internal" href="#c.NGHTTP2_ERR_NOMEM" title="NGHTTP2_ERR_NOMEM"><tt class="xref c c-macro docutils literal"><span class="pre">NGHTTP2_ERR_NOMEM</span></tt></a></dt>
 <dd>Out of memory.</dd>
 <dt><a class="reference internal" href="#c.NGHTTP2_ERR_INVALID_ARGUMENT" title="NGHTTP2_ERR_INVALID_ARGUMENT"><tt class="xref c c-macro docutils literal"><span class="pre">NGHTTP2_ERR_INVALID_ARGUMENT</span></tt></a></dt>
-<dd>The <em>pri_spec</em> is NULL; or trying to depend on itself.</dd>
+<dd>The <em>pri_spec</em> is NULL; or the <em>pri_spec-&gt;pri_type</em> is invalid;
+or trying to depend on itself.</dd>
 </dl>
 </dd></dl>
 
@@ -2740,16 +2750,19 @@ prioritized one first and the HTTP/2 specification requires the
 stream ID must be strictly increasing, the promised stream ID
 cannot be known until it is about to sent.  To know the promised
 stream ID, the application can use
-<a class="reference internal" href="#c.nghttp2_session_callbacks.before_frame_send_callback" title="nghttp2_session_callbacks.before_frame_send_callback"><tt class="xref c c-member docutils literal"><span class="pre">nghttp2_session_callbacks.before_frame_send_callback</span></tt></a>. This
+<a class="reference internal" href="#c.nghttp2_session_callbacks.before_frame_send_callback" title="nghttp2_session_callbacks.before_frame_send_callback"><tt class="xref c c-member docutils literal"><span class="pre">nghttp2_session_callbacks.before_frame_send_callback</span></tt></a>.
-callback is called just before the frame is sent. For PUSH_PROMISE
+This callback is called just before the frame is sent.  For
-frame, the argument frame has the promised stream ID assigned.</p>
+PUSH_PROMISE frame, the argument frame has the promised stream ID
-<p>The client side can use this function to send PUSH_PROMISE to the
+assigned.</p>
-server. But in normal HTTP usage, the server may treat it error.</p>
+<p>The client side is not allowed to use this function.</p>
 <p>This function returns 0 if it succeeds, or one of the following
 negative error codes:</p>
 <dl class="docutils">
 <dt><a class="reference internal" href="#c.NGHTTP2_ERR_NOMEM" title="NGHTTP2_ERR_NOMEM"><tt class="xref c c-macro docutils literal"><span class="pre">NGHTTP2_ERR_NOMEM</span></tt></a></dt>
 <dd>Out of memory.</dd>
+<dt><a class="reference internal" href="#c.NGHTTP2_ERR_PROTO" title="NGHTTP2_ERR_PROTO"><tt class="xref c c-macro docutils literal"><span class="pre">NGHTTP2_ERR_PROTO</span></tt></a></dt>
+<dd>This function was invoked when <em>session</em> is initialized as
+client.</dd>
 </dl>
 </dd></dl>
 
@@ -2842,7 +2855,7 @@ negative error codes:</p>
 <dl class="docutils">
 <dt><a class="reference internal" href="#c.NGHTTP2_ERR_NOMEM" title="NGHTTP2_ERR_NOMEM"><tt class="xref c c-macro docutils literal"><span class="pre">NGHTTP2_ERR_NOMEM</span></tt></a></dt>
 <dd>Out of memory.</dd>
-<dt><a class="reference internal" href="#c.NGHTTP2_ERR_INVALID_STATE" title="NGHTTP2_ERR_INVALID_STATE"><tt class="xref c c-macro docutils literal"><span class="pre">NGHTTP2_ERR_INVALID_STATE</span></tt></a></dt>
+<dt><a class="reference internal" href="#c.NGHTTP2_ERR_PROTO" title="NGHTTP2_ERR_PROTO"><tt class="xref c c-macro docutils literal"><span class="pre">NGHTTP2_ERR_PROTO</span></tt></a></dt>
 <dd>The function is invoked with <em>session</em> which was initialized as
 client.</dd>
 <dt><a class="reference internal" href="#c.NGHTTP2_ERR_INVALID_ARGUMENT" title="NGHTTP2_ERR_INVALID_ARGUMENT"><tt class="xref c c-macro docutils literal"><span class="pre">NGHTTP2_ERR_INVALID_ARGUMENT</span></tt></a></dt>
@@ -2854,10 +2867,11 @@ client.</dd>
 <dl class="function">
 <dt id="c.nghttp2_nv_compare_name">
 int <tt class="descname">nghttp2_nv_compare_name</tt><big>(</big>const <a class="reference internal" href="#c.nghttp2_nv" title="nghttp2_nv">nghttp2_nv</a><em>&nbsp;*lhs</em>, const <a class="reference internal" href="#c.nghttp2_nv" title="nghttp2_nv">nghttp2_nv</a><em>&nbsp;*rhs</em><big>)</big><a class="headerlink" href="#c.nghttp2_nv_compare_name" title="Permalink to this definition">¶</a></dt>
-<dd><p>Compares lhs-&gt;name with lhs-&gt;namelen bytes and rhs-&gt;name with
+<dd><p>Compares <tt class="docutils literal"><span class="pre">lhs-&gt;name</span></tt> of length <tt class="docutils literal"><span class="pre">lhs-&gt;namelen</span></tt> bytes and
-rhs-&gt;namelen bytes. Returns negative integer if lhs-&gt;name is found
+<tt class="docutils literal"><span class="pre">rhs-&gt;name</span></tt> of length <tt class="docutils literal"><span class="pre">rhs-&gt;namelen</span></tt> bytes.  Returns negative
-to be less than rhs-&gt;name; or returns positive integer if lhs-&gt;name
+integer if <tt class="docutils literal"><span class="pre">lhs-&gt;name</span></tt> is found to be less than <tt class="docutils literal"><span class="pre">rhs-&gt;name</span></tt>; or
-is found to be greater than rhs-&gt;name; or returns 0 otherwise.</p>
+returns positive integer if <tt class="docutils literal"><span class="pre">lhs-&gt;name</span></tt> is found to be greater
+than <tt class="docutils literal"><span class="pre">rhs-&gt;name</span></tt>; or returns 0 otherwise.</p>
 </dd></dl>
 
 <dl class="function">
@@ -2881,15 +2895,15 @@ null-terminated.  For example, <tt class="docutils literal"><span class="pre">HT
 it is selected and returns 1. The following step is not taken.</li>
 <li>If peer&#8217;s list contains <tt class="docutils literal"><span class="pre">http/1.1</span></tt>, this function selects
 <tt class="docutils literal"><span class="pre">http/1.1</span></tt> and returns 0.  The following step is not taken.</li>
-<li>This function selects nothing and returns -1. (So called
+<li>This function selects nothing and returns -1 (So called
 non-overlap case).  In this case, <em>out</em> and <em>outlen</em> are left
 untouched.</li>
 </ol>
 <p>Selecting <tt class="docutils literal"><span class="pre">HTTP-draft-04/2.0</span></tt> means that <tt class="docutils literal"><span class="pre">HTTP-draft-04/2.0</span></tt> is
-written into <em>*out</em> and its length (which is 17) is
+written into <em>*out</em> and its length (which is 17) is assigned to
-assigned to <em>*outlen</em>.</p>
+<em>*outlen</em>.</p>
 <p>For ALPN, refer to
-<a class="reference external" href="http://tools.ietf.org/html/draft-ietf-tls-applayerprotoneg-04">http://tools.ietf.org/html/draft-ietf-tls-applayerprotoneg-04</a></p>
+<a class="reference external" href="https://tools.ietf.org/html/draft-ietf-tls-applayerprotoneg-05">https://tools.ietf.org/html/draft-ietf-tls-applayerprotoneg-05</a></p>
 <p>See <a class="reference external" href="http://technotes.googlecode.com/git/nextprotoneg.html">http://technotes.googlecode.com/git/nextprotoneg.html</a> for more
 details about NPN.</p>
 <p>For NPN, to use this method you should do something like:</p>
@@ -2916,7 +2930,8 @@ details about NPN.</p>
 <dl class="function">
 <dt id="c.nghttp2_gzip_inflate_new">
 int <tt class="descname">nghttp2_gzip_inflate_new</tt><big>(</big><a class="reference internal" href="#c.nghttp2_gzip" title="nghttp2_gzip">nghttp2_gzip</a><em>&nbsp;**inflater_ptr</em><big>)</big><a class="headerlink" href="#c.nghttp2_gzip_inflate_new" title="Permalink to this definition">¶</a></dt>
-<dd><p>A helper function to set up a per request gzip stream to inflate data.</p>
+<dd><p>A helper function to set up a per request gzip stream to inflate
+data.</p>
 <p>This function returns 0 if it succeeds, or one of the following
 negative error codes:</p>
 <dl class="docutils">
@@ -2981,11 +2996,11 @@ negative error codes:</p>
 <dl class="function">
 <dt id="c.nghttp2_version">
 <a class="reference internal" href="#c.nghttp2_info" title="nghttp2_info">nghttp2_info</a> *<tt class="descname">nghttp2_version</tt><big>(</big>int<em>&nbsp;least_version</em><big>)</big><a class="headerlink" href="#c.nghttp2_version" title="Permalink to this definition">¶</a></dt>
-<dd><p>Returns a pointer to a nghttp2_info struct with version information about
+<dd><p>Returns a pointer to a nghttp2_info struct with version information
-the run-time library in use.  The <em>least_version</em> argument can be set to a
+about the run-time library in use.  The <em>least_version</em> argument
-24 bit numerical value for the least accepted version number and if the
+can be set to a 24 bit numerical value for the least accepted
-condition is not met, this function will return a NULL. Pass in 0 to skip
+version number and if the condition is not met, this function will
-the version checking.</p>
+return a <tt class="docutils literal"><span class="pre">NULL</span></tt>.  Pass in 0 to skip the version checking.</p>
 </dd></dl>
 
 <dl class="function">

nghttp2.h.html

@@ -390,8 +390,8 @@
 <span class="cm">   */</span>
   <span class="n">NGHTTP2_ERR_STREAM_CLOSED</span> <span class="o">=</span> <span class="o">-</span><span class="mi">510</span><span class="p">,</span>
   <span class="cm">/**</span>
-<span class="cm">   * RST_STREAM has been added to the outbound queue. The stream is in</span>
+<span class="cm">   * RST_STREAM has been added to the outbound queue.  The stream is</span>
-<span class="cm">   * closing state.</span>
+<span class="cm">   * in closing state.</span>
 <span class="cm">   */</span>
   <span class="n">NGHTTP2_ERR_STREAM_CLOSING</span> <span class="o">=</span> <span class="o">-</span><span class="mi">511</span><span class="p">,</span>
   <span class="cm">/**</span>
@@ -413,8 +413,8 @@
 <span class="cm">   */</span>
   <span class="n">NGHTTP2_ERR_DEFERRED_DATA_EXIST</span> <span class="o">=</span> <span class="o">-</span><span class="mi">515</span><span class="p">,</span>
   <span class="cm">/**</span>
-<span class="cm">   * Starting new stream is not allowed. (e.g., GOAWAY has been sent</span>
+<span class="cm">   * Starting new stream is not allowed (e.g., GOAWAY has been sent</span>
-<span class="cm">   * and/or received.</span>
+<span class="cm">   * and/or received).</span>
 <span class="cm">   */</span>
   <span class="n">NGHTTP2_ERR_START_STREAM_NOT_ALLOWED</span> <span class="o">=</span> <span class="o">-</span><span class="mi">516</span><span class="p">,</span>
   <span class="cm">/**</span>
@@ -422,11 +422,11 @@
 <span class="cm">   */</span>
   <span class="n">NGHTTP2_ERR_GOAWAY_ALREADY_SENT</span> <span class="o">=</span> <span class="o">-</span><span class="mi">517</span><span class="p">,</span>
   <span class="cm">/**</span>
-<span class="cm">   * The received frame contains the invalid header block. (e.g.,</span>
+<span class="cm">   * The received frame contains the invalid header block (e.g., There</span>
-<span class="cm">   * There are duplicate header names; or the header names are not</span>
+<span class="cm">   * are duplicate header names; or the header names are not encoded</span>
-<span class="cm">   * encoded in US-ASCII character set and not lower cased; or the</span>
+<span class="cm">   * in US-ASCII character set and not lower cased; or the header name</span>
-<span class="cm">   * header name is zero-length string; or the header value contains</span>
+<span class="cm">   * is zero-length string; or the header value contains multiple</span>
-<span class="cm">   * multiple in-sequence NUL bytes).</span>
+<span class="cm">   * in-sequence NUL bytes).</span>
 <span class="cm">   */</span>
   <span class="n">NGHTTP2_ERR_INVALID_HEADER_BLOCK</span> <span class="o">=</span> <span class="o">-</span><span class="mi">518</span><span class="p">,</span>
   <span class="cm">/**</span>
@@ -478,8 +478,11 @@
   <span class="n">NGHTTP2_ERR_DATA_EXIST</span> <span class="o">=</span> <span class="o">-</span><span class="mi">529</span><span class="p">,</span>
   <span class="cm">/**</span>
 <span class="cm">   * The errors &lt; :enum:`NGHTTP2_ERR_FATAL` mean that the library is</span>
-<span class="cm">   * under unexpected condition and cannot process any further data</span>
+<span class="cm">   * under unexpected condition and processing was terminated (e.g.,</span>
-<span class="cm">   * reliably (e.g., out of memory).</span>
+<span class="cm">   * out of memory).  If application receives this error code, it must</span>
+<span class="cm">   * stop using that :type:`nghttp2_session` object and only allowed</span>
+<span class="cm">   * operation for that object is deallocate it using</span>
+<span class="cm">   * `nghttp2_session_del()`.</span>
 <span class="cm">   */</span>
   <span class="n">NGHTTP2_ERR_FATAL</span> <span class="o">=</span> <span class="o">-</span><span class="mi">900</span><span class="p">,</span>
   <span class="cm">/**</span>
@@ -596,8 +599,8 @@
 <span class="cm">/**</span>
 <span class="cm"> * @enum</span>
 <span class="cm"> *</span>
-<span class="cm"> * The flags for HTTP/2 frames. This enum defines all flags for</span>
+<span class="cm"> * The flags for HTTP/2 frames.  This enum defines all flags for all</span>
-<span class="cm"> * frames, assuming that the same flag name has the same mask.</span>
+<span class="cm"> * frames.</span>
 <span class="cm"> */</span>
 <span class="k">typedef</span> <span class="k">enum</span> <span class="p">{</span>
   <span class="cm">/**</span>
@@ -792,22 +795,22 @@
 <span class="cm"> * @functypedef</span>
 <span class="cm"> *</span>
 <span class="cm"> * Callback function invoked when the library wants to read data from</span>
-<span class="cm"> * the |source|. The read data is sent in the stream |stream_id|. The</span>
+<span class="cm"> * the |source|.  The read data is sent in the stream |stream_id|.</span>
-<span class="cm"> * implementation of this function must read at most |length| bytes of</span>
+<span class="cm"> * The implementation of this function must read at most |length|</span>
-<span class="cm"> * data from |source| (or possibly other places) and store them in</span>
+<span class="cm"> * bytes of data from |source| (or possibly other places) and store</span>
-<span class="cm"> * |buf| and return number of data stored in |buf|. If EOF is reached,</span>
+<span class="cm"> * them in |buf| and return number of data stored in |buf|.  If EOF is</span>
-<span class="cm"> * set :enum:`NGHTTP2_DATA_FLAG_EOF` flag in |*data_falgs|.  If the</span>
+<span class="cm"> * reached, set :enum:`NGHTTP2_DATA_FLAG_EOF` flag in |*data_falgs|.</span>
-<span class="cm"> * application wants to postpone DATA frames, (e.g., asynchronous I/O,</span>
+<span class="cm"> * If the application wants to postpone DATA frames (e.g.,</span>
-<span class="cm"> * or reading data blocks for long time), it is achieved by returning</span>
+<span class="cm"> * asynchronous I/O, or reading data blocks for long time), it is</span>
-<span class="cm"> * :enum:`NGHTTP2_ERR_DEFERRED` without reading any data in this</span>
+<span class="cm"> * achieved by returning :enum:`NGHTTP2_ERR_DEFERRED` without reading</span>
-<span class="cm"> * invocation.  The library removes DATA frame from the outgoing queue</span>
+<span class="cm"> * any data in this invocation.  The library removes DATA frame from</span>
-<span class="cm"> * temporarily.  To move back deferred DATA frame to outgoing queue,</span>
+<span class="cm"> * the outgoing queue temporarily.  To move back deferred DATA frame</span>
-<span class="cm"> * call `nghttp2_session_resume_data()`.  In case of error, there are</span>
+<span class="cm"> * to outgoing queue, call `nghttp2_session_resume_data()`.  In case</span>
-<span class="cm"> * 2 choices. Returning :enum:`NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE`</span>
+<span class="cm"> * of error, there are 2 choices. Returning</span>
-<span class="cm"> * will close the stream by issuing RST_STREAM with</span>
+<span class="cm"> * :enum:`NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE` will close the stream</span>
-<span class="cm"> * :enum:`NGHTTP2_INTERNAL_ERROR`.  Returning</span>
+<span class="cm"> * by issuing RST_STREAM with :enum:`NGHTTP2_INTERNAL_ERROR`.</span>
-<span class="cm"> * :enum:`NGHTTP2_ERR_CALLBACK_FAILURE` will signal the entire session</span>
+<span class="cm"> * Returning :enum:`NGHTTP2_ERR_CALLBACK_FAILURE` will signal the</span>
-<span class="cm"> * failure.</span>
+<span class="cm"> * entire session failure.</span>
 <span class="cm"> */</span>
 <span class="k">typedef</span> <span class="nf">ssize_t</span> <span class="p">(</span><span class="o">*</span><span class="n">nghttp2_data_source_read_callback</span><span class="p">)</span>
 <span class="p">(</span><span class="n">nghttp2_session</span> <span class="o">*</span><span class="n">session</span><span class="p">,</span> <span class="kt">int32_t</span> <span class="n">stream_id</span><span class="p">,</span>
@@ -969,6 +972,7 @@
 
 <span class="cm">/**</span>
 <span class="cm"> * @struct</span>
+<span class="cm"> *</span>
 <span class="cm"> * The HEADERS frame.  It has the following members:</span>
 <span class="cm"> */</span>
 <span class="k">typedef</span> <span class="k">struct</span> <span class="p">{</span>
@@ -1001,6 +1005,7 @@
 
 <span class="cm">/**</span>
 <span class="cm"> * @struct</span>
+<span class="cm"> *</span>
 <span class="cm"> * The PRIORITY frame.  It has the following members:</span>
 <span class="cm"> */</span>
 <span class="k">typedef</span> <span class="k">struct</span> <span class="p">{</span>
@@ -1016,6 +1021,7 @@
 
 <span class="cm">/**</span>
 <span class="cm"> * @struct</span>
+<span class="cm"> *</span>
 <span class="cm"> * The RST_STREAM frame.  It has the following members:</span>
 <span class="cm"> */</span>
 <span class="k">typedef</span> <span class="k">struct</span> <span class="p">{</span>
@@ -1031,6 +1037,7 @@
 
 <span class="cm">/**</span>
 <span class="cm"> * @struct</span>
+<span class="cm"> *</span>
 <span class="cm"> * The SETTINGS ID/Value pair.  It has the following members:</span>
 <span class="cm"> */</span>
 <span class="k">typedef</span> <span class="k">struct</span> <span class="p">{</span>
@@ -1046,6 +1053,7 @@
 
 <span class="cm">/**</span>
 <span class="cm"> * @struct</span>
+<span class="cm"> *</span>
 <span class="cm"> * The SETTINGS frame.  It has the following members:</span>
 <span class="cm"> */</span>
 <span class="k">typedef</span> <span class="k">struct</span> <span class="p">{</span>
@@ -1065,6 +1073,7 @@
 
 <span class="cm">/**</span>
 <span class="cm"> * @struct</span>
+<span class="cm"> *</span>
 <span class="cm"> * The PUSH_PROMISE frame.  It has the following members:</span>
 <span class="cm"> */</span>
 <span class="k">typedef</span> <span class="k">struct</span> <span class="p">{</span>
@@ -1093,6 +1102,7 @@
 
 <span class="cm">/**</span>
 <span class="cm"> * @struct</span>
+<span class="cm"> *</span>
 <span class="cm"> * The PING frame.  It has the following members:</span>
 <span class="cm"> */</span>
 <span class="k">typedef</span> <span class="k">struct</span> <span class="p">{</span>
@@ -1108,6 +1118,7 @@
 
 <span class="cm">/**</span>
 <span class="cm"> * @struct</span>
+<span class="cm"> *</span>
 <span class="cm"> * The GOAWAY frame.  It has the following members:</span>
 <span class="cm"> */</span>
 <span class="k">typedef</span> <span class="k">struct</span> <span class="p">{</span>
@@ -1197,8 +1208,8 @@
 <span class="cm"> * @union</span>
 <span class="cm"> *</span>
 <span class="cm"> * This union includes all frames to pass them to various function</span>
-<span class="cm"> * calls as nghttp2_frame type. The CONTINUATION frame is omitted from</span>
+<span class="cm"> * calls as nghttp2_frame type.  The CONTINUATION frame is omitted</span>
-<span class="cm"> * here because the library deals with it internally.</span>
+<span class="cm"> * from here because the library deals with it internally.</span>
 <span class="cm"> */</span>
 <span class="k">typedef</span> <span class="k">union</span> <span class="p">{</span>
   <span class="cm">/**</span>
@@ -1255,15 +1266,15 @@
 <span class="cm"> * |length| bytes of data stored in |data|.  The |flags| is currently</span>
 <span class="cm"> * not used and always 0. It must return the number of bytes sent if</span>
 <span class="cm"> * it succeeds.  If it cannot send any single byte without blocking,</span>
-<span class="cm"> * it must return :enum:`NGHTTP2_ERR_WOULDBLOCK`. For other errors, it</span>
+<span class="cm"> * it must return :enum:`NGHTTP2_ERR_WOULDBLOCK`.  For other errors,</span>
-<span class="cm"> * must return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`. The |user_data|</span>
+<span class="cm"> * it must return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`.  The</span>
-<span class="cm"> * pointer is the third argument passed in to the call to</span>
+<span class="cm"> * |user_data| pointer is the third argument passed in to the call to</span>
 <span class="cm"> * `nghttp2_session_client_new()` or `nghttp2_session_server_new()`.</span>
 <span class="cm"> *</span>
 <span class="cm"> * This callback is required if the application uses</span>
 <span class="cm"> * `nghttp2_session_send()` to send data to the remote endpoint.  If</span>
-<span class="cm"> * the application uses `nghttp2_session_mem_send()` instead, this</span>
+<span class="cm"> * the application uses solely `nghttp2_session_mem_send()` instead,</span>
-<span class="cm"> * callback function is unnecessary.</span>
+<span class="cm"> * this callback function is unnecessary.</span>
 <span class="cm"> */</span>
 <span class="k">typedef</span> <span class="nf">ssize_t</span> <span class="p">(</span><span class="o">*</span><span class="n">nghttp2_send_callback</span><span class="p">)</span>
 <span class="p">(</span><span class="n">nghttp2_session</span> <span class="o">*</span><span class="n">session</span><span class="p">,</span>
@@ -1275,19 +1286,19 @@
 <span class="cm"> * Callback function invoked when |session| wants to receive data from</span>
 <span class="cm"> * the remote peer.  The implementation of this function must read at</span>
 <span class="cm"> * most |length| bytes of data and store it in |buf|.  The |flags| is</span>
-<span class="cm"> * currently not used and always 0. It must return the number of bytes</span>
+<span class="cm"> * currently not used and always 0.  It must return the number of</span>
-<span class="cm"> * written in |buf| if it succeeds. If it cannot read any single byte</span>
+<span class="cm"> * bytes written in |buf| if it succeeds.  If it cannot read any</span>
-<span class="cm"> * without blocking, it must return :enum:`NGHTTP2_ERR_WOULDBLOCK`. If</span>
+<span class="cm"> * single byte without blocking, it must return</span>
-<span class="cm"> * it gets EOF before it reads any single byte, it must return</span>
+<span class="cm"> * :enum:`NGHTTP2_ERR_WOULDBLOCK`.  If it gets EOF before it reads any</span>
-<span class="cm"> * :enum:`NGHTTP2_ERR_EOF`. For other errors, it must return</span>
+<span class="cm"> * single byte, it must return :enum:`NGHTTP2_ERR_EOF`.  For other</span>
-<span class="cm"> * :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`. Returning 0 is treated as</span>
+<span class="cm"> * errors, it must return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`.</span>
-<span class="cm"> * :enum:`NGHTTP2_ERR_WOULDBLOCK`. The |user_data| pointer is the</span>
+<span class="cm"> * Returning 0 is treated as :enum:`NGHTTP2_ERR_WOULDBLOCK`.  The</span>
-<span class="cm"> * third argument passed in to the call to</span>
+<span class="cm"> * |user_data| pointer is the third argument passed in to the call to</span>
 <span class="cm"> * `nghttp2_session_client_new()` or `nghttp2_session_server_new()`.</span>
 <span class="cm"> *</span>
 <span class="cm"> * This callback is required if the application uses</span>
-<span class="cm"> * `nghttp2_session_recv()` to receive data from the remote</span>
+<span class="cm"> * `nghttp2_session_recv()` to receive data from the remote endpoint.</span>
-<span class="cm"> * endpoint. If the application uses `nghttp2_session_mem_recv()`</span>
+<span class="cm"> * If the application uses solely `nghttp2_session_mem_recv()`</span>
 <span class="cm"> * instead, this callback function is unnecessary.</span>
 <span class="cm"> */</span>
 <span class="k">typedef</span> <span class="nf">ssize_t</span> <span class="p">(</span><span class="o">*</span><span class="n">nghttp2_recv_callback</span><span class="p">)</span>
@@ -1297,7 +1308,7 @@
 <span class="cm">/**</span>
 <span class="cm"> * @functypedef</span>
 <span class="cm"> *</span>
-<span class="cm"> * Callback function invoked by `nghttp2_session_recv()` when a aframe</span>
+<span class="cm"> * Callback function invoked by `nghttp2_session_recv()` when a frame</span>
 <span class="cm"> * is received.  The |user_data| pointer is the third argument passed</span>
 <span class="cm"> * in to the call to `nghttp2_session_client_new()` or</span>
 <span class="cm"> * `nghttp2_session_server_new()`.</span>
@@ -1313,14 +1324,14 @@
 <span class="cm"> * check that stream is still alive using its own stream management or</span>
 <span class="cm"> * :func:`nghttp2_session_get_stream_user_data()`.</span>
 <span class="cm"> *</span>
-<span class="cm"> * Only HEADERS and DATA frame can signal the end of incoming data. If</span>
+<span class="cm"> * Only HEADERS and DATA frame can signal the end of incoming data.</span>
-<span class="cm"> * ``frame-&gt;hd.flags &amp; NGHTTP2_FLAG_END_STREAM`` is nonzero, the</span>
+<span class="cm"> * If ``frame-&gt;hd.flags &amp; NGHTTP2_FLAG_END_STREAM`` is nonzero, the</span>
 <span class="cm"> * |frame| is the last frame from the remote peer in this stream.</span>
 <span class="cm"> *</span>
-<span class="cm"> * The implementation of this function must return 0 if it</span>
+<span class="cm"> * The implementation of this function must return 0 if it succeeds.</span>
-<span class="cm"> * succeeds. If nonzero value is returned, it is treated as fatal</span>
+<span class="cm"> * If nonzero value is returned, it is treated as fatal error and</span>
-<span class="cm"> * error and `nghttp2_session_recv()` and `nghttp2_session_mem_recv()`</span>
+<span class="cm"> * `nghttp2_session_recv()` and `nghttp2_session_mem_recv()` functions</span>
-<span class="cm"> * functions immediately return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`.</span>
+<span class="cm"> * immediately return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`.</span>
 <span class="cm"> */</span>
 <span class="k">typedef</span> <span class="nf">int</span> <span class="p">(</span><span class="o">*</span><span class="n">nghttp2_on_frame_recv_callback</span><span class="p">)</span>
 <span class="p">(</span><span class="n">nghttp2_session</span> <span class="o">*</span><span class="n">session</span><span class="p">,</span> <span class="k">const</span> <span class="n">nghttp2_frame</span> <span class="o">*</span><span class="n">frame</span><span class="p">,</span> <span class="kt">void</span> <span class="o">*</span><span class="n">user_data</span><span class="p">);</span>
@@ -1340,8 +1351,8 @@
 <span class="cm"> * member of their data structure are always ``NULL`` and 0</span>
 <span class="cm"> * respectively.</span>
 <span class="cm"> *</span>
-<span class="cm"> * The implementation of this function must return 0 if it</span>
+<span class="cm"> * The implementation of this function must return 0 if it succeeds.</span>
-<span class="cm"> * succeeds. If nonzero is returned, it is treated as fatal error and</span>
+<span class="cm"> * If nonzero is returned, it is treated as fatal error and</span>
 <span class="cm"> * `nghttp2_session_recv()` and `nghttp2_session_send()` functions</span>
 <span class="cm"> * immediately return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`.</span>
 <span class="cm"> */</span>
@@ -1354,25 +1365,25 @@
 <span class="cm"> *</span>
 <span class="cm"> * Callback function invoked when a chunk of data in DATA frame is</span>
 <span class="cm"> * received.  The |stream_id| is the stream ID this DATA frame belongs</span>
-<span class="cm"> * to. The |flags| is the flags of DATA frame which this data chunk is</span>
+<span class="cm"> * to.  The |flags| is the flags of DATA frame which this data chunk</span>
-<span class="cm"> * contained. ``(flags &amp; NGHTTP2_FLAG_END_STREAM) != 0`` does not</span>
+<span class="cm"> * is contained.  ``(flags &amp; NGHTTP2_FLAG_END_STREAM) != 0`` does not</span>
-<span class="cm"> * necessarily mean this chunk of data is the last one in the</span>
+<span class="cm"> * necessarily mean this chunk of data is the last one in the stream.</span>
-<span class="cm"> * stream. You should use :type:`nghttp2_on_frame_recv_callback` to</span>
+<span class="cm"> * You should use :type:`nghttp2_on_frame_recv_callback` to know all</span>
-<span class="cm"> * know all data frames are received. The |user_data| pointer is the</span>
+<span class="cm"> * data frames are received.  The |user_data| pointer is the third</span>
-<span class="cm"> * third argument passed in to the call to</span>
+<span class="cm"> * argument passed in to the call to `nghttp2_session_client_new()` or</span>
-<span class="cm"> * `nghttp2_session_client_new()` or `nghttp2_session_server_new()`.</span>
+<span class="cm"> * `nghttp2_session_server_new()`.</span>
 <span class="cm"> *</span>
 <span class="cm"> * If the application uses `nghttp2_session_mem_recv()`, it can return</span>
 <span class="cm"> * :enum:`NGHTTP2_ERR_PAUSE` to make `nghttp2_session_mem_recv()`</span>
 <span class="cm"> * return without processing further input bytes.  The memory by</span>
 <span class="cm"> * pointed by the |data| is retained until</span>
-<span class="cm"> * `nghttp2_session_mem_recv()` or `nghttp2_session_recv()` is</span>
+<span class="cm"> * `nghttp2_session_mem_recv()` or `nghttp2_session_recv()` is called.</span>
-<span class="cm"> * called. The application must retain the input bytes which was used</span>
+<span class="cm"> * The application must retain the input bytes which was used to</span>
-<span class="cm"> * to produce the |data| parameter, because it may refer to the memory</span>
+<span class="cm"> * produce the |data| parameter, because it may refer to the memory</span>
 <span class="cm"> * region included in the input bytes.</span>
 <span class="cm"> *</span>
-<span class="cm"> * The implementation of this function must return 0 if it</span>
+<span class="cm"> * The implementation of this function must return 0 if it succeeds.</span>
-<span class="cm"> * succeeds. If nonzero is returned, it is treated as fatal error and</span>
+<span class="cm"> * If nonzero is returned, it is treated as fatal error and</span>
 <span class="cm"> * `nghttp2_session_recv()` and `nghttp2_session_mem_recv()` functions</span>
 <span class="cm"> * immediately return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`.</span>
 <span class="cm"> */</span>
@@ -1391,8 +1402,8 @@
 <span class="cm"> * passed in to the call to `nghttp2_session_client_new()` or</span>
 <span class="cm"> * `nghttp2_session_server_new()`.</span>
 <span class="cm"> *</span>
-<span class="cm"> * The implementation of this function must return 0 if it</span>
+<span class="cm"> * The implementation of this function must return 0 if it succeeds.</span>
-<span class="cm"> * succeeds. If nonzero is returned, it is treated as fatal error and</span>
+<span class="cm"> * If nonzero is returned, it is treated as fatal error and</span>
 <span class="cm"> * `nghttp2_session_recv()` and `nghttp2_session_send()` functions</span>
 <span class="cm"> * immediately return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`.</span>
 <span class="cm"> */</span>
@@ -1406,8 +1417,8 @@
 <span class="cm"> * |user_data| pointer is the third argument passed in to the call to</span>
 <span class="cm"> * `nghttp2_session_client_new()` or `nghttp2_session_server_new()`.</span>
 <span class="cm"> *</span>
-<span class="cm"> * The implementation of this function must return 0 if it</span>
+<span class="cm"> * The implementation of this function must return 0 if it succeeds.</span>
-<span class="cm"> * succeeds. If nonzero is returned, it is treated as fatal error and</span>
+<span class="cm"> * If nonzero is returned, it is treated as fatal error and</span>
 <span class="cm"> * `nghttp2_session_recv()` and `nghttp2_session_send()` functions</span>
 <span class="cm"> * immediately return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`.</span>
 <span class="cm"> */</span>
@@ -1424,8 +1435,8 @@
 <span class="cm"> * argument passed in to the call to `nghttp2_session_client_new()` or</span>
 <span class="cm"> * `nghttp2_session_server_new()`.</span>
 <span class="cm"> *</span>
-<span class="cm"> * The implementation of this function must return 0 if it</span>
+<span class="cm"> * The implementation of this function must return 0 if it succeeds.</span>
-<span class="cm"> * succeeds. If nonzero is returned, it is treated as fatal error and</span>
+<span class="cm"> * If nonzero is returned, it is treated as fatal error and</span>
 <span class="cm"> * `nghttp2_session_recv()` and `nghttp2_session_send()` functions</span>
 <span class="cm"> * immediately return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`.</span>
 <span class="cm"> */</span>
@@ -1436,16 +1447,18 @@
 <span class="cm">/**</span>
 <span class="cm"> * @functypedef</span>
 <span class="cm"> *</span>
-<span class="cm"> * Callback function invoked when the stream |stream_id| is</span>
+<span class="cm"> * Callback function invoked when the stream |stream_id| is closed.</span>
-<span class="cm"> * closed. The reason of closure is indicated by the |error_code|. The</span>
+<span class="cm"> * The reason of closure is indicated by the |error_code|.  The</span>
 <span class="cm"> * stream_user_data, which was specified in `nghttp2_submit_request()`</span>
-<span class="cm"> * or `nghttp2_submit_headers()`, is still available in this</span>
+<span class="cm"> * or `nghttp2_submit_headers()`, is still available in this function.</span>
-<span class="cm"> * function. The |user_data| pointer is the third argument passed in</span>
+<span class="cm"> * The |user_data| pointer is the third argument passed in to the call</span>
-<span class="cm"> * to the call to `nghttp2_session_client_new()` or</span>
+<span class="cm"> * to `nghttp2_session_client_new()` or</span>
 <span class="cm"> * `nghttp2_session_server_new()`.</span>
 <span class="cm"> *</span>
-<span class="cm"> * The implementation of this function must return 0 if it</span>
+<span class="cm"> * This function is also called for a stream in reserved state.</span>
-<span class="cm"> * succeeds. If nonzero is returned, it is treated as fatal error and</span>
+<span class="cm"> *</span>
+<span class="cm"> * The implementation of this function must return 0 if it succeeds.</span>
+<span class="cm"> * If nonzero is returned, it is treated as fatal error and</span>
 <span class="cm"> * `nghttp2_session_recv()` and `nghttp2_session_send()` functions</span>
 <span class="cm"> * immediately return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`.</span>
 <span class="cm"> */</span>
@@ -1456,19 +1469,18 @@
 <span class="cm">/**</span>
 <span class="cm"> * @functypedef</span>
 <span class="cm"> *</span>
-<span class="cm"> * Callback function invoked when the received frame type is</span>
+<span class="cm"> * Callback function invoked when the received frame type is unknown.</span>
-<span class="cm"> * unknown. The |head| is the pointer to the header of the received</span>
+<span class="cm"> * The |head| is the pointer to the header of the received frame.  The</span>
-<span class="cm"> * frame. The |headlen| is the length of the |head|. According to the</span>
+<span class="cm"> * |headlen| is the length of the |head|.  According to the spec, the</span>
-<span class="cm"> * spec, the |headlen| is always 8. In other words, the |head| is the</span>
+<span class="cm"> * |headlen| is always 8.  In other words, the |head| is the first 8</span>
-<span class="cm"> * first 8 bytes of the received frame.  The |payload| is the pointer</span>
+<span class="cm"> * bytes of the received frame.  The |payload| is the pointer to the</span>
-<span class="cm"> * to the data portion of the received frame.  The |payloadlen| is the</span>
+<span class="cm"> * data portion of the received frame.  The |payloadlen| is the length</span>
-<span class="cm"> * length of the |payload|. This is the data after the length</span>
+<span class="cm"> * of the |payload|.  This is the data after the length field.  The</span>
-<span class="cm"> * field. The |user_data| pointer is the third argument passed in to</span>
+<span class="cm"> * |user_data| pointer is the third argument passed in to the call to</span>
-<span class="cm"> * the call to `nghttp2_session_client_new()` or</span>
+<span class="cm"> * `nghttp2_session_client_new()` or `nghttp2_session_server_new()`.</span>
-<span class="cm"> * `nghttp2_session_server_new()`.</span>
 <span class="cm"> *</span>
-<span class="cm"> * The implementation of this function must return 0 if it</span>
+<span class="cm"> * The implementation of this function must return 0 if it succeeds.</span>
-<span class="cm"> * succeeds. If nonzero is returned, it is treated as fatal error and</span>
+<span class="cm"> * If nonzero is returned, it is treated as fatal error and</span>
 <span class="cm"> * `nghttp2_session_recv()` and `nghttp2_session_send()` functions</span>
 <span class="cm"> * immediately return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`.</span>
 <span class="cm"> */</span>
@@ -1543,18 +1555,18 @@
 <span class="cm"> * :enum:`NGHTTP2_ERR_PAUSE` to make `nghttp2_session_mem_recv()`</span>
 <span class="cm"> * return without processing further input bytes.  The memory pointed</span>
 <span class="cm"> * by |frame|, |name| and |value| parameters are retained until</span>
-<span class="cm"> * `nghttp2_session_mem_recv()` or `nghttp2_session_recv()` is</span>
+<span class="cm"> * `nghttp2_session_mem_recv()` or `nghttp2_session_recv()` is called.</span>
-<span class="cm"> * called. The application must retain the input bytes which was used</span>
+<span class="cm"> * The application must retain the input bytes which was used to</span>
-<span class="cm"> * to produce these parameters, because it may refer to the memory</span>
+<span class="cm"> * produce these parameters, because it may refer to the memory region</span>
-<span class="cm"> * region included in the input bytes.</span>
+<span class="cm"> * included in the input bytes.</span>
 <span class="cm"> *</span>
 <span class="cm"> * Returning :enum:`NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE` will close</span>
 <span class="cm"> * the stream by issuing RST_STREAM with</span>
 <span class="cm"> * :enum:`NGHTTP2_INTERNAL_ERROR`.  In this case,</span>
 <span class="cm"> * :type:`nghttp2_on_frame_recv_callback` will not be invoked.</span>
 <span class="cm"> *</span>
-<span class="cm"> * The implementation of this function must return 0 if it</span>
+<span class="cm"> * The implementation of this function must return 0 if it succeeds.</span>
-<span class="cm"> * succeeds. It may return :enum:`NGHTTP2_ERR_PAUSE` or</span>
+<span class="cm"> * It may return :enum:`NGHTTP2_ERR_PAUSE` or</span>
 <span class="cm"> * :enum:`NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE`.  For other critical</span>
 <span class="cm"> * failures, it must return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`.  If</span>
 <span class="cm"> * the other nonzero value is returned, it is treated as</span>
@@ -1575,9 +1587,9 @@
 <span class="cm"> * @functypedef</span>
 <span class="cm"> *</span>
 <span class="cm"> * Callback function invoked when the library asks application how</span>
-<span class="cm"> * much padding is required for the transmission of the |frame|. The</span>
+<span class="cm"> * many padding bytes are required for the transmission of the</span>
-<span class="cm"> * application must choose the total length of payload including</span>
+<span class="cm"> * |frame|.  The application must choose the total length of payload</span>
-<span class="cm"> * padded bytes in range [frame-&gt;hd.length, max_payloadlen],</span>
+<span class="cm"> * including padded bytes in range [frame-&gt;hd.length, max_payloadlen],</span>
 <span class="cm"> * inclusive.  Choosing number not in this range will be treated as</span>
 <span class="cm"> * :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`.  Returning</span>
 <span class="cm"> * ``frame-&gt;hd.length`` means no padding is added.  Returning</span>
@@ -1600,15 +1612,15 @@
   <span class="cm">/**</span>
 <span class="cm">   * Callback function invoked when the |session| wants to send data</span>
 <span class="cm">   * to the remote peer.  This callback is not necessary if the</span>
-<span class="cm">   * application uses `nghttp2_session_mem_send()` to serialize data</span>
+<span class="cm">   * application uses solely `nghttp2_session_mem_send()` to serialize</span>
-<span class="cm">   * to transmit.</span>
+<span class="cm">   * data to transmit.</span>
 <span class="cm">   */</span>
   <span class="n">nghttp2_send_callback</span> <span class="n">send_callback</span><span class="p">;</span>
   <span class="cm">/**</span>
 <span class="cm">   * Callback function invoked when the |session| wants to receive</span>
 <span class="cm">   * data from the remote peer.  This callback is not necessary if the</span>
-<span class="cm">   * application uses `nghttp2_session_mem_recv()` to process received</span>
+<span class="cm">   * application uses solely `nghttp2_session_mem_recv()` to process</span>
-<span class="cm">   * data.</span>
+<span class="cm">   * received data.</span>
 <span class="cm">   */</span>
   <span class="n">nghttp2_recv_callback</span> <span class="n">recv_callback</span><span class="p">;</span>
   <span class="cm">/**</span>
@@ -1660,7 +1672,8 @@
   <span class="n">nghttp2_on_header_callback</span> <span class="n">on_header_callback</span><span class="p">;</span>
   <span class="cm">/**</span>
 <span class="cm">   * Callback function invoked when the library asks application how</span>
-<span class="cm">   * much padding is required for the transmission of the given frame.</span>
+<span class="cm">   * many padding bytes are required for the transmission of the given</span>
+<span class="cm">   * frame.</span>
 <span class="cm">   */</span>
   <span class="n">nghttp2_select_padding_callback</span> <span class="n">select_padding_callback</span><span class="p">;</span>
 <span class="p">}</span> <span class="n">nghttp2_session_callbacks</span><span class="p">;</span>
@@ -1718,9 +1731,9 @@
 <span class="cm"> * This option prevents the library from sending WINDOW_UPDATE for a</span>
 <span class="cm"> * connection automatically.  If this option is set to nonzero, the</span>
 <span class="cm"> * library won&#39;t send WINDOW_UPDATE for a connection and the</span>
-<span class="cm"> * application is responsible for sending WINDOW_UPDATE with stream</span>
+<span class="cm"> * application is responsible for sending WINDOW_UPDATE with stream ID</span>
-<span class="cm"> * ID 0 using `nghttp2_submit_window_update`. By default, this</span>
+<span class="cm"> * 0 using `nghttp2_submit_window_update`.  By default, this option is</span>
-<span class="cm"> * option is set to zero.</span>
+<span class="cm"> * set to zero.</span>
 <span class="cm"> */</span>
 <span class="kt">void</span> <span class="nf">nghttp2_option_set_no_auto_connection_window_update</span>
 <span class="p">(</span><span class="n">nghttp2_option</span> <span class="o">*</span><span class="n">option</span><span class="p">,</span> <span class="kt">int</span> <span class="n">val</span><span class="p">);</span>
@@ -1733,11 +1746,11 @@
 <span class="cm"> * specifying this option, before the local endpoint receives</span>
 <span class="cm"> * SETTINGS_MAX_CONCURRENT_STREAMS in SETTINGS frame from remote</span>
 <span class="cm"> * endpoint, SETTINGS_MAX_CONCURRENT_STREAMS is unlimited.  This may</span>
-<span class="cm"> * cause problem if local endpoint submits lots of requests</span>
+<span class="cm"> * cause problem if local endpoint submits lots of requests initially</span>
-<span class="cm"> * initially and sending them at once to the remote peer may lead to</span>
+<span class="cm"> * and sending them at once to the remote peer may lead to the</span>
-<span class="cm"> * the rejection of some requests. Specifying this option to the</span>
+<span class="cm"> * rejection of some requests.  Specifying this option to the sensible</span>
-<span class="cm"> * sensible value, say 100, may avoid this kind of issue. This value</span>
+<span class="cm"> * value, say 100, may avoid this kind of issue. This value will be</span>
-<span class="cm"> * will be overwritten if the local endpoint receives</span>
+<span class="cm"> * overwritten if the local endpoint receives</span>
 <span class="cm"> * SETTINGS_MAX_CONCURRENT_STREAMS from the remote endpoint.</span>
 <span class="cm"> */</span>
 <span class="kt">void</span> <span class="nf">nghttp2_option_set_peer_max_concurrent_streams</span><span class="p">(</span><span class="n">nghttp2_option</span> <span class="o">*</span><span class="n">option</span><span class="p">,</span>
@@ -1748,7 +1761,7 @@
 <span class="cm"> *</span>
 <span class="cm"> * Initializes |*session_ptr| for client use.  The all members of</span>
 <span class="cm"> * |callbacks| are copied to |*session_ptr|.  Therefore |*session_ptr|</span>
-<span class="cm"> * does not store |callbacks|. |user_data| is an arbitrary user</span>
+<span class="cm"> * does not store |callbacks|.  The |user_data| is an arbitrary user</span>
 <span class="cm"> * supplied data, which will be passed to the callback functions.</span>
 <span class="cm"> *</span>
 <span class="cm"> * The :member:`nghttp2_session_callbacks.send_callback` must be</span>
@@ -1771,7 +1784,7 @@
 <span class="cm"> *</span>
 <span class="cm"> * Initializes |*session_ptr| for server use.  The all members of</span>
 <span class="cm"> * |callbacks| are copied to |*session_ptr|. Therefore |*session_ptr|</span>
-<span class="cm"> * does not store |callbacks|. |user_data| is an arbitrary user</span>
+<span class="cm"> * does not store |callbacks|.  The |user_data| is an arbitrary user</span>
 <span class="cm"> * supplied data, which will be passed to the callback functions.</span>
 <span class="cm"> *</span>
 <span class="cm"> * The :member:`nghttp2_session_callbacks.send_callback` must be</span>
@@ -1866,19 +1879,20 @@
 <span class="cm"> * 1. Get the next frame to send from outbound queue.</span>
 <span class="cm"> * 2. Prepare transmission of the frame.</span>
 <span class="cm"> * 3. If the control frame cannot be sent because some preconditions</span>
-<span class="cm"> *    are not met (e.g., request HEADERS cannot be sent after</span>
+<span class="cm"> *    are not met (e.g., request HEADERS cannot be sent after GOAWAY),</span>
-<span class="cm"> *    GOAWAY),</span>
+<span class="cm"> *    :member:`nghttp2_session_callbacks.on_frame_not_send_callback`</span>
-<span class="cm"> *    :member:`nghttp2_session_callbacks.on_frame_not_send_callback` is</span>
+<span class="cm"> *    is invoked.  Abort the following steps.</span>
-<span class="cm"> *    invoked. Abort the following steps.</span>
+<span class="cm"> * 4. If the frame is HEADERS, PUSH_PROMISE or DATA,</span>
-<span class="cm"> * 4. If the frame is request HEADERS, the stream is opened</span>
+<span class="cm"> *    :member:`nghttp2_session_callbacks.select_padding_callback` is</span>
-<span class="cm"> *    here.</span>
-<span class="cm"> * 5. :member:`nghttp2_session_callbacks.before_frame_send_callback` is</span>
 <span class="cm"> *    invoked.</span>
-<span class="cm"> * 6. :member:`nghttp2_session_callbacks.send_callback` is invoked one</span>
+<span class="cm"> * 5. If the frame is request HEADERS, the stream is opened here.</span>
+<span class="cm"> * 6. :member:`nghttp2_session_callbacks.before_frame_send_callback` is</span>
+<span class="cm"> *    invoked.</span>
+<span class="cm"> * 7. :member:`nghttp2_session_callbacks.send_callback` is invoked one</span>
 <span class="cm"> *    or more times to send the frame.</span>
-<span class="cm"> * 7. :member:`nghttp2_session_callbacks.on_frame_send_callback` is</span>
+<span class="cm"> * 8. :member:`nghttp2_session_callbacks.on_frame_send_callback` is</span>
 <span class="cm"> *    invoked.</span>
-<span class="cm"> * 8. If the transmission of the frame triggers closure of the stream,</span>
+<span class="cm"> * 9. If the transmission of the frame triggers closure of the stream,</span>
 <span class="cm"> *    the stream is closed and</span>
 <span class="cm"> *    :member:`nghttp2_session_callbacks.on_stream_close_callback` is</span>
 <span class="cm"> *    invoked.</span>
@@ -1898,17 +1912,18 @@
 <span class="cm"> *</span>
 <span class="cm"> * Returns the serialized data to send.</span>
 <span class="cm"> *</span>
-<span class="cm"> * This function behaves like `nghttp2_session_send()` except that</span>
+<span class="cm"> * This function behaves like `nghttp2_session_send()` except that it</span>
-<span class="cm"> * it does not use :member:`nghttp2_session_callbacks.send_callback`</span>
+<span class="cm"> * does not use :member:`nghttp2_session_callbacks.send_callback` to</span>
-<span class="cm"> * to transmit data. Instead, it assigns the pointer to the serialized</span>
+<span class="cm"> * transmit data.  Instead, it assigns the pointer to the serialized</span>
-<span class="cm"> * data to the |*data_ptr| and returns its length. The other callbacks</span>
+<span class="cm"> * data to the |*data_ptr| and returns its length.  The other</span>
-<span class="cm"> * are called in the same way as they are in `nghttp2_session_send()`.</span>
+<span class="cm"> * callbacks are called in the same way as they are in</span>
+<span class="cm"> * `nghttp2_session_send()`.</span>
 <span class="cm"> *</span>
 <span class="cm"> * If no data is available to send, this function returns 0.</span>
 <span class="cm"> *</span>
-<span class="cm"> * This function may not return all serialized data in one</span>
+<span class="cm"> * This function may not return all serialized data in one invocation.</span>
-<span class="cm"> * invocation. To get all data, call this function repeatedly until it</span>
+<span class="cm"> * To get all data, call this function repeatedly until it returns 0</span>
-<span class="cm"> * returns 0 or one of negative error codes.</span>
+<span class="cm"> * or one of negative error codes.</span>
 <span class="cm"> *</span>
 <span class="cm"> * The assigned |*data_ptr| is valid until the next call of</span>
 <span class="cm"> * `nghttp2_session_mem_send()` or `nghttp2_session_send()`.</span>
@@ -2086,8 +2101,8 @@
 <span class="cm"> * @function</span>
 <span class="cm"> *</span>
 <span class="cm"> * Sets the |stream_user_data| to the stream denoted by the</span>
-<span class="cm"> * |stream_id|. If a stream user data is already set to the stream, it</span>
+<span class="cm"> * |stream_id|.  If a stream user data is already set to the stream,</span>
-<span class="cm"> * is replaced with the |stream_user_data|. It is valid to specify</span>
+<span class="cm"> * it is replaced with the |stream_user_data|.  It is valid to specify</span>
 <span class="cm"> * ``NULL`` in the |stream_user_data|, which nullifies the associated</span>
 <span class="cm"> * data pointer.</span>
 <span class="cm"> *</span>
@@ -2132,8 +2147,8 @@
 <span class="cm">/**</span>
 <span class="cm"> * @function</span>
 <span class="cm"> *</span>
-<span class="cm"> * Returns the local (receive) window size for the stream</span>
+<span class="cm"> * Returns the local (receive) window size for the stream |stream_id|.</span>
-<span class="cm"> * |stream_id|. The local window size can be adjusted by</span>
+<span class="cm"> * The local window size can be adjusted by</span>
 <span class="cm"> * `nghttp2_submit_window_update()`.  This function takes into account</span>
 <span class="cm"> * that and returns effective window size.</span>
 <span class="cm"> *</span>
@@ -2147,12 +2162,12 @@
 <span class="cm"> *</span>
 <span class="cm"> * Returns the number of DATA payload in bytes received without</span>
 <span class="cm"> * WINDOW_UPDATE transmission for a connection.  The local (receive)</span>
-<span class="cm"> * window size can be adjusted by</span>
+<span class="cm"> * window size can be adjusted by `nghttp2_submit_window_update()`.</span>
-<span class="cm"> * `nghttp2_submit_window_update()`. This function takes into account</span>
+<span class="cm"> * This function takes into account that and returns effective data</span>
-<span class="cm"> * that and returns effective data length. In particular, if the local</span>
+<span class="cm"> * length.  In particular, if the local window size is reduced by</span>
-<span class="cm"> * window size is reduced by submitting negative window_size_increment</span>
+<span class="cm"> * submitting negative window_size_increment with</span>
-<span class="cm"> * with `nghttp2_submit_window_update()`, this function returns the</span>
+<span class="cm"> * `nghttp2_submit_window_update()`, this function returns the number</span>
-<span class="cm"> * number of bytes less than actually received.</span>
+<span class="cm"> * of bytes less than actually received.</span>
 <span class="cm"> *</span>
 <span class="cm"> * This function returns -1 if it fails.</span>
 <span class="cm"> */</span>
@@ -2162,8 +2177,8 @@
 <span class="cm">/**</span>
 <span class="cm"> * @function</span>
 <span class="cm"> *</span>
-<span class="cm"> * Returns the local (receive) window size for a connection. The local</span>
+<span class="cm"> * Returns the local (receive) window size for a connection.  The</span>
-<span class="cm"> * window size can be adjusted by</span>
+<span class="cm"> * local window size can be adjusted by</span>
 <span class="cm"> * `nghttp2_submit_window_update()`.  This function takes into account</span>
 <span class="cm"> * that and returns effective window size.</span>
 <span class="cm"> *</span>
@@ -2198,8 +2213,8 @@
 <span class="cm"> * function succeeds.</span>
 <span class="cm"> *</span>
 <span class="cm"> * This function should be called when the connection should be</span>
-<span class="cm"> * terminated after sending GOAWAY. If the remaining streams should be</span>
+<span class="cm"> * terminated after sending GOAWAY.  If the remaining streams should</span>
-<span class="cm"> * processed after GOAWAY, use `nghttp2_submit_goaway()` instead.</span>
+<span class="cm"> * be processed after GOAWAY, use `nghttp2_submit_goaway()` instead.</span>
 <span class="cm"> *</span>
 <span class="cm"> * This function returns 0 if it succeeds, or one of the following</span>
 <span class="cm"> * negative error codes:</span>
@@ -2213,20 +2228,19 @@
 <span class="cm">/**</span>
 <span class="cm"> * @function</span>
 <span class="cm"> *</span>
-<span class="cm"> * Performs post-process of HTTP Upgrade request. This function can be</span>
+<span class="cm"> * Performs post-process of HTTP Upgrade request.  This function can</span>
-<span class="cm"> * called from both client and server, but the behavior is very</span>
+<span class="cm"> * be called from both client and server, but the behavior is very</span>
 <span class="cm"> * different in each other.</span>
 <span class="cm"> *</span>
 <span class="cm"> * If called from client side, the |settings_payload| must be the</span>
 <span class="cm"> * value sent in ``HTTP2-Settings`` header field and must be decoded</span>
 <span class="cm"> * by base64url decoder.  The |settings_payloadlen| is the length of</span>
 <span class="cm"> * |settings_payload|.  The |settings_payload| is unpacked and its</span>
-<span class="cm"> * setting values will be submitted using</span>
+<span class="cm"> * setting values will be submitted using `nghttp2_submit_settings()`.</span>
-<span class="cm"> * `nghttp2_submit_settings()`. This means that the client application</span>
+<span class="cm"> * This means that the client application code does not need to submit</span>
-<span class="cm"> * code does not need to submit SETTINGS by itself. The stream with</span>
+<span class="cm"> * SETTINGS by itself.  The stream with stream ID=1 is opened and the</span>
-<span class="cm"> * stream ID=1 is opened and the |stream_user_data| is used for its</span>
+<span class="cm"> * |stream_user_data| is used for its stream_user_data.  The opened</span>
-<span class="cm"> * stream_user_data. The opened stream becomes half-closed (local)</span>
+<span class="cm"> * stream becomes half-closed (local) state.</span>
-<span class="cm"> * state.</span>
 <span class="cm"> *</span>
 <span class="cm"> * If called from server side, the |settings_payload| must be the</span>
 <span class="cm"> * value received in ``HTTP2-Settings`` header field and must be</span>
@@ -2358,8 +2372,8 @@
 <span class="cm"> * stream ID must be strictly increasing, the stream ID of this</span>
 <span class="cm"> * request cannot be known until it is about to sent.  To know the</span>
 <span class="cm"> * stream ID of the request, the application can use</span>
-<span class="cm"> * :member:`nghttp2_session_callbacks.before_frame_send_callback`. This</span>
+<span class="cm"> * :member:`nghttp2_session_callbacks.before_frame_send_callback`.</span>
-<span class="cm"> * callback is called just before the frame is sent. For HEADERS</span>
+<span class="cm"> * This callback is called just before the frame is sent.  For HEADERS</span>
 <span class="cm"> * frame, the argument frame has the stream ID assigned.  Also since</span>
 <span class="cm"> * the stream is already opened,</span>
 <span class="cm"> * `nghttp2_session_get_stream_user_data()` can be used to get</span>
@@ -2370,6 +2384,8 @@
 <span class="cm"> *</span>
 <span class="cm"> * :enum:`NGHTTP2_ERR_NOMEM`</span>
 <span class="cm"> *     Out of memory.</span>
+<span class="cm"> * :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`</span>
+<span class="cm"> *     The |pri_spec-&gt;pri_type| is invalid.</span>
 <span class="cm"> */</span>
 <span class="kt">int</span> <span class="nf">nghttp2_submit_request</span><span class="p">(</span><span class="n">nghttp2_session</span> <span class="o">*</span><span class="n">session</span><span class="p">,</span>
                            <span class="k">const</span> <span class="n">nghttp2_priority_spec</span> <span class="o">*</span><span class="n">pri_spec</span><span class="p">,</span>
@@ -2402,11 +2418,11 @@
 <span class="cm"> * |data_prd|.  If |data_prd| is ``NULL``, HEADERS will have</span>
 <span class="cm"> * END_STREAM flag set.</span>
 <span class="cm"> *</span>
-<span class="cm"> * This method can be used as normal HTTP response and push</span>
+<span class="cm"> * This method can be used as normal HTTP response and push response.</span>
-<span class="cm"> * response. When pushing a resource using this function, the</span>
+<span class="cm"> * When pushing a resource using this function, the |session| must be</span>
-<span class="cm"> * |session| must be configured using `nghttp2_session_server_new()`</span>
+<span class="cm"> * configured using `nghttp2_session_server_new()` or its variants and</span>
-<span class="cm"> * or its variants and the target stream denoted by the |stream_id|</span>
+<span class="cm"> * the target stream denoted by the |stream_id| must be reserved using</span>
-<span class="cm"> * must be reserved using `nghttp2_submit_push_promise()`.</span>
+<span class="cm"> * `nghttp2_submit_push_promise()`.</span>
 <span class="cm"> *</span>
 <span class="cm"> * This function returns 0 if it succeeds, or one of the following</span>
 <span class="cm"> * negative error codes:</span>
@@ -2457,9 +2473,9 @@
 <span class="cm"> * also lower-cases all names in |nva|.</span>
 <span class="cm"> *</span>
 <span class="cm"> * The |stream_user_data| is a pointer to an arbitrary data which is</span>
-<span class="cm"> * associated to the stream this frame will open. Therefore it is only</span>
+<span class="cm"> * associated to the stream this frame will open.  Therefore it is</span>
-<span class="cm"> * used if this frame opens streams, in other words, it changes stream</span>
+<span class="cm"> * only used if this frame opens streams, in other words, it changes</span>
-<span class="cm"> * state from idle or reserved to open.</span>
+<span class="cm"> * stream state from idle or reserved to open.</span>
 <span class="cm"> *</span>
 <span class="cm"> * This function is low-level in a sense that the application code can</span>
 <span class="cm"> * specify flags directly.  For usual HTTP request,</span>
@@ -2470,6 +2486,8 @@
 <span class="cm"> *</span>
 <span class="cm"> * :enum:`NGHTTP2_ERR_NOMEM`</span>
 <span class="cm"> *     Out of memory.</span>
+<span class="cm"> * :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`</span>
+<span class="cm"> *     The |pri_spec-&gt;pri_type| is invalid.</span>
 <span class="cm"> */</span>
 <span class="kt">int</span> <span class="nf">nghttp2_submit_headers</span><span class="p">(</span><span class="n">nghttp2_session</span> <span class="o">*</span><span class="n">session</span><span class="p">,</span> <span class="kt">uint8_t</span> <span class="n">flags</span><span class="p">,</span>
                            <span class="kt">int32_t</span> <span class="n">stream_id</span><span class="p">,</span>
@@ -2483,8 +2501,8 @@
 <span class="cm"> * Submits one or more DATA frames to the stream |stream_id|.  The</span>
 <span class="cm"> * data to be sent are provided by |data_prd|.  If |flags| contains</span>
 <span class="cm"> * :enum:`NGHTTP2_FLAG_END_STREAM`, the last DATA frame has END_STREAM</span>
-<span class="cm"> * flag set. If |flags| contains :enum:`NGHTTP2_FLAG_END_SEGMENT`, the</span>
+<span class="cm"> * flag set.  If |flags| contains :enum:`NGHTTP2_FLAG_END_SEGMENT`,</span>
-<span class="cm"> * last DATA frame has END_SEGMENT flag set.</span>
+<span class="cm"> * the last DATA frame has END_SEGMENT flag set.</span>
 <span class="cm"> *</span>
 <span class="cm"> * This function does not take ownership of the |data_prd|.  The</span>
 <span class="cm"> * function copies the members of the |data_prd|.</span>
@@ -2522,7 +2540,8 @@
 <span class="cm"> * :enum:`NGHTTP2_ERR_NOMEM`</span>
 <span class="cm"> *     Out of memory.</span>
 <span class="cm"> * :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`</span>
-<span class="cm"> *     The |pri_spec| is NULL; or trying to depend on itself.</span>
+<span class="cm"> *     The |pri_spec| is NULL; or the |pri_spec-&gt;pri_type| is invalid;</span>
+<span class="cm"> *     or trying to depend on itself.</span>
 <span class="cm"> */</span>
 <span class="kt">int</span> <span class="nf">nghttp2_submit_priority</span><span class="p">(</span><span class="n">nghttp2_session</span> <span class="o">*</span><span class="n">session</span><span class="p">,</span> <span class="kt">uint8_t</span> <span class="n">flags</span><span class="p">,</span>
                             <span class="kt">int32_t</span> <span class="n">stream_id</span><span class="p">,</span>
@@ -2617,18 +2636,21 @@
 <span class="cm"> * stream ID must be strictly increasing, the promised stream ID</span>
 <span class="cm"> * cannot be known until it is about to sent.  To know the promised</span>
 <span class="cm"> * stream ID, the application can use</span>
-<span class="cm"> * :member:`nghttp2_session_callbacks.before_frame_send_callback`. This</span>
+<span class="cm"> * :member:`nghttp2_session_callbacks.before_frame_send_callback`.</span>
-<span class="cm"> * callback is called just before the frame is sent. For PUSH_PROMISE</span>
+<span class="cm"> * This callback is called just before the frame is sent.  For</span>
-<span class="cm"> * frame, the argument frame has the promised stream ID assigned.</span>
+<span class="cm"> * PUSH_PROMISE frame, the argument frame has the promised stream ID</span>
+<span class="cm"> * assigned.</span>
 <span class="cm"> *</span>
-<span class="cm"> * The client side can use this function to send PUSH_PROMISE to the</span>
+<span class="cm"> * The client side is not allowed to use this function.</span>
-<span class="cm"> * server. But in normal HTTP usage, the server may treat it error.</span>
 <span class="cm"> *</span>
 <span class="cm"> * This function returns 0 if it succeeds, or one of the following</span>
 <span class="cm"> * negative error codes:</span>
 <span class="cm"> *</span>
 <span class="cm"> * :enum:`NGHTTP2_ERR_NOMEM`</span>
 <span class="cm"> *     Out of memory.</span>
+<span class="cm"> * :enum:`NGHTTP2_ERR_PROTO`</span>
+<span class="cm"> *     This function was invoked when |session| is initialized as</span>
+<span class="cm"> *     client.</span>
 <span class="cm"> */</span>
 <span class="kt">int</span> <span class="nf">nghttp2_submit_push_promise</span><span class="p">(</span><span class="n">nghttp2_session</span> <span class="o">*</span><span class="n">session</span><span class="p">,</span> <span class="kt">uint8_t</span> <span class="n">flags</span><span class="p">,</span>
                                 <span class="kt">int32_t</span> <span class="n">stream_id</span><span class="p">,</span>
@@ -2746,7 +2768,7 @@
 <span class="cm"> *</span>
 <span class="cm"> * :enum:`NGHTTP2_ERR_NOMEM`</span>
 <span class="cm"> *     Out of memory.</span>
-<span class="cm"> * :enum:`NGHTTP2_ERR_INVALID_STATE`</span>
+<span class="cm"> * :enum:`NGHTTP2_ERR_PROTO`</span>
 <span class="cm"> *     The function is invoked with |session| which was initialized as</span>
 <span class="cm"> *     client.</span>
 <span class="cm"> * :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`</span>
@@ -2763,10 +2785,11 @@
 <span class="cm">/**</span>
 <span class="cm"> * @function</span>
 <span class="cm"> *</span>
-<span class="cm"> * Compares lhs-&gt;name with lhs-&gt;namelen bytes and rhs-&gt;name with</span>
+<span class="cm"> * Compares ``lhs-&gt;name`` of length ``lhs-&gt;namelen`` bytes and</span>
-<span class="cm"> * rhs-&gt;namelen bytes. Returns negative integer if lhs-&gt;name is found</span>
+<span class="cm"> * ``rhs-&gt;name`` of length ``rhs-&gt;namelen`` bytes.  Returns negative</span>
-<span class="cm"> * to be less than rhs-&gt;name; or returns positive integer if lhs-&gt;name</span>
+<span class="cm"> * integer if ``lhs-&gt;name`` is found to be less than ``rhs-&gt;name``; or</span>
-<span class="cm"> * is found to be greater than rhs-&gt;name; or returns 0 otherwise.</span>
+<span class="cm"> * returns positive integer if ``lhs-&gt;name`` is found to be greater</span>
+<span class="cm"> * than ``rhs-&gt;name``; or returns 0 otherwise.</span>
 <span class="cm"> */</span>
 <span class="kt">int</span> <span class="nf">nghttp2_nv_compare_name</span><span class="p">(</span><span class="k">const</span> <span class="n">nghttp2_nv</span> <span class="o">*</span><span class="n">lhs</span><span class="p">,</span> <span class="k">const</span> <span class="n">nghttp2_nv</span> <span class="o">*</span><span class="n">rhs</span><span class="p">);</span>
 
@@ -2793,16 +2816,16 @@
 <span class="cm"> * 2. If peer&#39;s list contains ``http/1.1``, this function selects</span>
 <span class="cm"> *    ``http/1.1`` and returns 0.  The following step is not taken.</span>
 <span class="cm"> *</span>
-<span class="cm"> * 3. This function selects nothing and returns -1. (So called</span>
+<span class="cm"> * 3. This function selects nothing and returns -1 (So called</span>
 <span class="cm"> *    non-overlap case).  In this case, |out| and |outlen| are left</span>
 <span class="cm"> *    untouched.</span>
 <span class="cm"> *</span>
 <span class="cm"> * Selecting ``HTTP-draft-04/2.0`` means that ``HTTP-draft-04/2.0`` is</span>
-<span class="cm"> * written into |*out| and its length (which is 17) is</span>
+<span class="cm"> * written into |*out| and its length (which is 17) is assigned to</span>
-<span class="cm"> * assigned to |*outlen|.</span>
+<span class="cm"> * |*outlen|.</span>
 <span class="cm"> *</span>
 <span class="cm"> * For ALPN, refer to</span>
-<span class="cm"> * http://tools.ietf.org/html/draft-ietf-tls-applayerprotoneg-04</span>
+<span class="cm"> * https://tools.ietf.org/html/draft-ietf-tls-applayerprotoneg-05</span>
 <span class="cm"> *</span>
 <span class="cm"> * See http://technotes.googlecode.com/git/nextprotoneg.html for more</span>
 <span class="cm"> * details about NPN.</span>
@@ -2843,7 +2866,8 @@
 <span class="cm">/**</span>
 <span class="cm"> * @function</span>
 <span class="cm"> *</span>
-<span class="cm"> * A helper function to set up a per request gzip stream to inflate data.</span>
+<span class="cm"> * A helper function to set up a per request gzip stream to inflate</span>
+<span class="cm"> * data.</span>
 <span class="cm"> *</span>
 <span class="cm"> * This function returns 0 if it succeeds, or one of the following</span>
 <span class="cm"> * negative error codes:</span>
@@ -2913,11 +2937,11 @@
 <span class="cm">/**</span>
 <span class="cm"> * @function</span>
 <span class="cm"> *</span>
-<span class="cm"> * Returns a pointer to a nghttp2_info struct with version information about</span>
+<span class="cm"> * Returns a pointer to a nghttp2_info struct with version information</span>
-<span class="cm"> * the run-time library in use.  The |least_version| argument can be set to a</span>
+<span class="cm"> * about the run-time library in use.  The |least_version| argument</span>
-<span class="cm"> * 24 bit numerical value for the least accepted version number and if the</span>
+<span class="cm"> * can be set to a 24 bit numerical value for the least accepted</span>
-<span class="cm"> * condition is not met, this function will return a NULL. Pass in 0 to skip</span>
+<span class="cm"> * version number and if the condition is not met, this function will</span>
-<span class="cm"> * the version checking.</span>
+<span class="cm"> * return a ``NULL``.  Pass in 0 to skip the version checking.</span>
 <span class="cm"> */</span>
 <span class="n">nghttp2_info</span> <span class="o">*</span><span class="nf">nghttp2_version</span><span class="p">(</span><span class="kt">int</span> <span class="n">least_version</span><span class="p">);</span>
 

package_README.html

@@ -521,10 +521,10 @@ IPv6: listen on port 8080
 a reverse proxy and listens for <tt class="docutils literal"><span class="pre">h2-11</span></tt>, SPDY and HTTP/1.1 and can
 be deployed SSL/TLS terminator for existing web server.</p>
 <p>The default mode, <tt class="docutils literal"><span class="pre">--http2-proxy</span></tt> and <tt class="docutils literal"><span class="pre">--http2-bridge</span></tt> modes use
-SSL/TLS in the frontend connection by default. To disable SSL/TLS, use
+SSL/TLS in the frontend connection by default.  To disable SSL/TLS,
-<tt class="docutils literal"><span class="pre">--frontend-no-tls</span></tt> option. If that option is used, SPDY is disabled
+use <tt class="docutils literal"><span class="pre">--frontend-no-tls</span></tt> option.  If that option is used, SPDY is
-in the frontend and incoming HTTP/1.1 connection can be upgraded to
+disabled in the frontend and incoming HTTP/1.1 connection can be
-HTTP/2 through HTTP Upgrade.</p>
+upgraded to HTTP/2 through HTTP Upgrade.</p>
 <p>The <tt class="docutils literal"><span class="pre">--http2-bridge</span></tt>, <tt class="docutils literal"><span class="pre">--client</span></tt> and <tt class="docutils literal"><span class="pre">--client-proxy</span></tt> modes use
 SSL/TLS in the backend connection by deafult.  To disable SSL/TLS, use
 <tt class="docutils literal"><span class="pre">--backend-no-tls</span></tt> option.</p>
@@ -586,11 +586,11 @@ the backend is HTTP/2 Web server:</p>
 <p>The frontend HTTP/1.1 connection can be upgraded to HTTP/2
 through HTTP Upgrade.</p>
 <p>For the operation modes which talk to the backend in HTTP/2 over
-SSL/TLS, the backend connections can be tunneled through HTTP
+SSL/TLS, the backend connections can be tunneled through HTTP proxy.
-proxy. The proxy is specified using <tt class="docutils literal"><span class="pre">--backend-http-proxy-uri</span></tt>
+The proxy is specified using <tt class="docutils literal"><span class="pre">--backend-http-proxy-uri</span></tt> option.  The
-option. The following figure illustrates the example of
+following figure illustrates the example of <tt class="docutils literal"><span class="pre">--http2-bridge</span></tt> and
-<tt class="docutils literal"><span class="pre">--http2-bridge</span></tt> and <tt class="docutils literal"><span class="pre">--backend-http-proxy-uri</span></tt> options to talk to
+<tt class="docutils literal"><span class="pre">--backend-http-proxy-uri</span></tt> options to talk to the outside HTTP/2
-the outside HTTP/2 proxy through HTTP proxy:</p>
+proxy through HTTP proxy:</p>
 <div class="highlight-c"><div class="highlight"><pre><span class="n">Client</span> <span class="o">&lt;--</span> <span class="p">(</span><span class="n">HTTP</span><span class="o">/</span><span class="mi">2</span><span class="p">,</span> <span class="n">SPDY</span><span class="p">,</span> <span class="n">HTTP</span><span class="o">/</span><span class="mf">1.1</span><span class="p">)</span> <span class="o">--&gt;</span> <span class="n">nghttpx</span> <span class="o">&lt;--</span> <span class="p">(</span><span class="n">HTTP</span><span class="o">/</span><span class="mi">2</span><span class="p">)</span> <span class="o">--</span>
 
         <span class="o">--===================---&gt;</span> <span class="n">HTTP</span><span class="o">/</span><span class="mi">2</span> <span class="n">Proxy</span>
@@ -603,9 +603,9 @@ the outside HTTP/2 proxy through HTTP proxy:</p>
 <h2>Benchmarking tool<a class="headerlink" href="#benchmarking-tool" title="Permalink to this headline">¶</a></h2>
 <p>The <tt class="docutils literal"><span class="pre">h2load</span></tt> program is a benchmarking tool for HTTP/2 and SPDY.
 The SPDY support is enabled if the program was built with spdylay
-library. The UI of <tt class="docutils literal"><span class="pre">h2load</span></tt> is heavily inspired by
+library.  The UI of <tt class="docutils literal"><span class="pre">h2load</span></tt> is heavily inspired by <tt class="docutils literal"><span class="pre">weighttp</span></tt>
-<tt class="docutils literal"><span class="pre">weighttp</span></tt> (<a class="reference external" href="https://github.com/lighttpd/weighttp">https://github.com/lighttpd/weighttp</a>). The typical usage
+(<a class="reference external" href="https://github.com/lighttpd/weighttp">https://github.com/lighttpd/weighttp</a>).  The typical usage is as
-is as follows:</p>
+follows:</p>
 <div class="highlight-c"><div class="highlight"><pre>$ src/h2load -n1000 -c10 -m10 https://127.0.0.1:8443/
 starting benchmark...
 progress: 10% done
@@ -631,8 +631,8 @@ With <tt class="docutils literal"><span class="pre">-t</span></tt> option, <tt c
 avoid saturating single core on client side.</p>
 <div class="admonition warning">
 <p class="first admonition-title">Warning</p>
-<p class="last"><strong>Don&#8217;t use this tool against publicly available servers.</strong> That
+<p class="last"><strong>Don&#8217;t use this tool against publicly available servers.</strong> That is
-is considered a DOS attack. Please only use against your private
+considered a DOS attack.  Please only use against your private
 servers.</p>
 </div>
 </div>
@@ -641,16 +641,16 @@ servers.</p>
 <p>The <tt class="docutils literal"><span class="pre">src</span></tt> directory contains HPACK tools.  The <tt class="docutils literal"><span class="pre">deflatehd</span></tt> is a
 command-line header compression tool.  The <tt class="docutils literal"><span class="pre">inflatehd</span></tt> is
 command-line header decompression tool.  Both tools read input from
-stdin and write output to stdout. The errors are written to
+stdin and write output to stdout.  The errors are written to stderr.
-stderr. They take JSON as input and output. We use the same JSON data
+They take JSON as input and output.  We use (mostly) same JSON data
-format used in <a class="reference external" href="https://github.com/Jxck/hpack-test-case">https://github.com/Jxck/hpack-test-case</a></p>
+format described at <a class="reference external" href="https://github.com/http2jp/hpack-test-case">https://github.com/http2jp/hpack-test-case</a></p>
 <div class="section" id="deflatehd-header-compressor">
 <h3>deflatehd - header compressor<a class="headerlink" href="#deflatehd-header-compressor" title="Permalink to this headline">¶</a></h3>
 <p>The <tt class="docutils literal"><span class="pre">deflatehd</span></tt> reads JSON data or HTTP/1-style header fields from
 stdin and outputs compressed header block in JSON.</p>
-<p>For the JSON input, the root JSON object must include <tt class="docutils literal"><span class="pre">cases</span></tt>
+<p>For the JSON input, the root JSON object must include <tt class="docutils literal"><span class="pre">cases</span></tt> key.
-key. Its value has to include the sequence of input header set. They
+Its value has to include the sequence of input header set.  They share
-share the same compression context and are processed in the order they
+the same compression context and are processed in the order they
 appear.  Each item in the sequence is a JSON object and it must
 include <tt class="docutils literal"><span class="pre">headers</span></tt> key.  Its value is an array of a JSON object,
 which includes exactly one name/value pair.</p>
@@ -766,18 +766,15 @@ value is an array of JSON object, which has at least following keys:</p>
 <tt class="docutils literal"><span class="pre">deflatehd</span></tt>.</p>
 <p>With <tt class="docutils literal"><span class="pre">-d</span></tt> option, the extra <tt class="docutils literal"><span class="pre">header_table</span></tt> key is added and its
 associated value includes the state of dynamic header table after the
-corresponding header set was processed. The value includes at least the
+corresponding header set was processed.  The value includes at least
-following keys:</p>
+the following keys:</p>
 <dl class="docutils">
 <dt>entries</dt>
 <dd>The entry in the header table.  If <tt class="docutils literal"><span class="pre">referenced</span></tt> is <tt class="docutils literal"><span class="pre">true</span></tt>, it
 is in the reference set.  The <tt class="docutils literal"><span class="pre">size</span></tt> includes the overhead (32
 bytes).  The <tt class="docutils literal"><span class="pre">index</span></tt> corresponds to the index of header table.
 The <tt class="docutils literal"><span class="pre">name</span></tt> is the header field name and the <tt class="docutils literal"><span class="pre">value</span></tt> is the
-header field value. They may be displayed as <tt class="docutils literal"><span class="pre">**DEALLOCATED**</span></tt>,
+header field value.</dd>
-which means that the memory for that string is freed and not
-available. This will happen when the specifying smaller value in
-<tt class="docutils literal"><span class="pre">-S</span></tt> than <tt class="docutils literal"><span class="pre">-s</span></tt>.</dd>
 <dt>size</dt>
 <dd>The sum of the spaces entries occupied, this includes the
 entry overhead.</dd>
@@ -1043,8 +1040,8 @@ corresponding header set was processed. The format is the same as
 <div class="section" id="python-bindings">
 <h2>Python bindings<a class="headerlink" href="#python-bindings" title="Permalink to this headline">¶</a></h2>
 <p>This <tt class="docutils literal"><span class="pre">python</span></tt> directory contains nghttp2 Python bindings.  The
-bindings currently provide HPACK compressor and decompressor
+bindings currently provide HPACK compressor and decompressor classes
-classes and HTTP/2 server.</p>
+and HTTP/2 server.</p>
 <p>The extension module is called <tt class="docutils literal"><span class="pre">nghttp2</span></tt>.</p>
 <p><tt class="docutils literal"><span class="pre">make</span></tt> will build the bindings and target Python version is
 determined by configure script.  If the detected Python version is not
@@ -1068,19 +1065,19 @@ and decompressor in Python:</p>
 </pre></div>
 </div>
 <p>The <tt class="docutils literal"><span class="pre">nghttp2.HTTP2Server</span></tt> class builds on top of the asyncio event
-loop. On construction, <em>RequestHandlerClass</em> must be given, which must
+loop.  On construction, <em>RequestHandlerClass</em> must be given, which
-be a subclass of <tt class="docutils literal"><span class="pre">nghttp2.BaseRequestHandler</span></tt> class.</p>
+must be a subclass of <tt class="docutils literal"><span class="pre">nghttp2.BaseRequestHandler</span></tt> class.</p>
-<p>The <tt class="docutils literal"><span class="pre">BaseRequestHandler</span></tt> class is used to handle the HTTP/2
+<p>The <tt class="docutils literal"><span class="pre">BaseRequestHandler</span></tt> class is used to handle the HTTP/2 stream.
-stream. By default, it does nothing. It must be subclassed to
+By default, it does nothing.  It must be subclassed to handle each
-handle each event callback method.</p>
+event callback method.</p>
 <p>The first callback method invoked is <tt class="docutils literal"><span class="pre">on_headers()</span></tt>.  It is called
 when HEADERS frame, which includes request header fields, has arrived.</p>
 <p>If request has request body, <tt class="docutils literal"><span class="pre">on_data(data)</span></tt> is invoked for each
 chunk of received data.</p>
 <p>When whole request is received, <tt class="docutils literal"><span class="pre">on_request_done()</span></tt> is invoked.</p>
 <p>When stream is closed, <tt class="docutils literal"><span class="pre">on_close(error_code)</span></tt> is called.</p>
-<p>The application can send response using <tt class="docutils literal"><span class="pre">send_response()</span></tt> method. It
+<p>The application can send response using <tt class="docutils literal"><span class="pre">send_response()</span></tt> method.
-can be used in <tt class="docutils literal"><span class="pre">on_headers()</span></tt>, <tt class="docutils literal"><span class="pre">on_data()</span></tt> or
+It can be used in <tt class="docutils literal"><span class="pre">on_headers()</span></tt>, <tt class="docutils literal"><span class="pre">on_data()</span></tt> or
 <tt class="docutils literal"><span class="pre">on_request_done()</span></tt>.</p>
 <p>The application can push resource using <tt class="docutils literal"><span class="pre">push()</span></tt> method.  It must be
 used before <tt class="docutils literal"><span class="pre">send_response()</span></tt> call.</p>
@@ -1092,7 +1089,8 @@ client&#8217;s address.</dd>
 <dt>stream_id</dt>
 <dd>Stream ID of this stream.</dd>
 <dt>scheme</dt>
-<dd>Scheme of the request URI. This is a value of :scheme header field.</dd>
+<dd>Scheme of the request URI.  This is a value of :scheme header
+field.</dd>
 <dt>method</dt>
 <dd>Method of this stream.  This is a value of :method header field.</dd>
 <dt>host</dt>