Update doc

lib/includes/nghttp2/nghttp2.h

@@ -240,8 +240,8 @@ typedef enum {
    */
   NGHTTP2_ERR_STREAM_CLOSED = -510,
   /**
-   * RST_STREAM has been added to the outbound queue. The stream is in
-   * closing state.
+   * RST_STREAM has been added to the outbound queue.  The stream is
+   * in closing state.
    */
   NGHTTP2_ERR_STREAM_CLOSING = -511,
   /**
@@ -263,8 +263,8 @@ typedef enum {
    */
   NGHTTP2_ERR_DEFERRED_DATA_EXIST = -515,
   /**
-   * Starting new stream is not allowed. (e.g., GOAWAY has been sent
-   * and/or received.
+   * Starting new stream is not allowed (e.g., GOAWAY has been sent
+   * and/or received).
    */
   NGHTTP2_ERR_START_STREAM_NOT_ALLOWED = -516,
   /**
@@ -272,11 +272,11 @@ typedef enum {
    */
   NGHTTP2_ERR_GOAWAY_ALREADY_SENT = -517,
   /**
-   * The received frame contains the invalid header block. (e.g.,
-   * There are duplicate header names; or the header names are not
-   * encoded in US-ASCII character set and not lower cased; or the
-   * header name is zero-length string; or the header value contains
-   * multiple in-sequence NUL bytes).
+   * The received frame contains the invalid header block (e.g., There
+   * are duplicate header names; or the header names are not encoded
+   * in US-ASCII character set and not lower cased; or the header name
+   * is zero-length string; or the header value contains multiple
+   * in-sequence NUL bytes).
    */
   NGHTTP2_ERR_INVALID_HEADER_BLOCK = -518,
   /**
@@ -328,8 +328,11 @@ typedef enum {
   NGHTTP2_ERR_DATA_EXIST = -529,
   /**
    * The errors < :enum:`NGHTTP2_ERR_FATAL` mean that the library is
-   * under unexpected condition and cannot process any further data
-   * reliably (e.g., out of memory).
+   * under unexpected condition and processing was terminated (e.g.,
+   * out of memory).  If application receives this error code, it must
+   * stop using that :type:`nghttp2_session` object and only allowed
+   * operation for that object is deallocate it using
+   * `nghttp2_session_del()`.
    */
   NGHTTP2_ERR_FATAL = -900,
   /**
@@ -446,8 +449,8 @@ typedef enum {
 /**
  * @enum
  *
- * The flags for HTTP/2 frames. This enum defines all flags for
- * frames, assuming that the same flag name has the same mask.
+ * The flags for HTTP/2 frames.  This enum defines all flags for all
+ * frames.
  */
 typedef enum {
   /**
@@ -642,22 +645,22 @@ typedef enum {
  * @functypedef
  *
  * Callback function invoked when the library wants to read data from
- * the |source|. The read data is sent in the stream |stream_id|. The
- * implementation of this function must read at most |length| bytes of
- * data from |source| (or possibly other places) and store them in
- * |buf| and return number of data stored in |buf|. If EOF is reached,
- * set :enum:`NGHTTP2_DATA_FLAG_EOF` flag in |*data_falgs|.  If the
- * application wants to postpone DATA frames, (e.g., asynchronous I/O,
- * or reading data blocks for long time), it is achieved by returning
- * :enum:`NGHTTP2_ERR_DEFERRED` without reading any data in this
- * invocation.  The library removes DATA frame from the outgoing queue
- * temporarily.  To move back deferred DATA frame to outgoing queue,
- * call `nghttp2_session_resume_data()`.  In case of error, there are
- * 2 choices. Returning :enum:`NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE`
- * will close the stream by issuing RST_STREAM with
- * :enum:`NGHTTP2_INTERNAL_ERROR`.  Returning
- * :enum:`NGHTTP2_ERR_CALLBACK_FAILURE` will signal the entire session
- * failure.
+ * the |source|.  The read data is sent in the stream |stream_id|.
+ * The implementation of this function must read at most |length|
+ * bytes of data from |source| (or possibly other places) and store
+ * them in |buf| and return number of data stored in |buf|.  If EOF is
+ * reached, set :enum:`NGHTTP2_DATA_FLAG_EOF` flag in |*data_falgs|.
+ * If the application wants to postpone DATA frames (e.g.,
+ * asynchronous I/O, or reading data blocks for long time), it is
+ * achieved by returning :enum:`NGHTTP2_ERR_DEFERRED` without reading
+ * any data in this invocation.  The library removes DATA frame from
+ * the outgoing queue temporarily.  To move back deferred DATA frame
+ * to outgoing queue, call `nghttp2_session_resume_data()`.  In case
+ * of error, there are 2 choices. Returning
+ * :enum:`NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE` will close the stream
+ * by issuing RST_STREAM with :enum:`NGHTTP2_INTERNAL_ERROR`.
+ * Returning :enum:`NGHTTP2_ERR_CALLBACK_FAILURE` will signal the
+ * entire session failure.
  */
 typedef ssize_t (*nghttp2_data_source_read_callback)
 (nghttp2_session *session, int32_t stream_id,
@@ -819,6 +822,7 @@ typedef struct {
 
 /**
  * @struct
+ *
  * The HEADERS frame.  It has the following members:
  */
 typedef struct {
@@ -851,6 +855,7 @@ typedef struct {
 
 /**
  * @struct
+ *
  * The PRIORITY frame.  It has the following members:
  */
 typedef struct {
@@ -866,6 +871,7 @@ typedef struct {
 
 /**
  * @struct
+ *
  * The RST_STREAM frame.  It has the following members:
  */
 typedef struct {
@@ -881,6 +887,7 @@ typedef struct {
 
 /**
  * @struct
+ *
  * The SETTINGS ID/Value pair.  It has the following members:
  */
 typedef struct {
@@ -896,6 +903,7 @@ typedef struct {
 
 /**
  * @struct
+ *
  * The SETTINGS frame.  It has the following members:
  */
 typedef struct {
@@ -915,6 +923,7 @@ typedef struct {
 
 /**
  * @struct
+ *
  * The PUSH_PROMISE frame.  It has the following members:
  */
 typedef struct {
@@ -943,6 +952,7 @@ typedef struct {
 
 /**
  * @struct
+ *
  * The PING frame.  It has the following members:
  */
 typedef struct {
@@ -958,6 +968,7 @@ typedef struct {
 
 /**
  * @struct
+ *
  * The GOAWAY frame.  It has the following members:
  */
 typedef struct {
@@ -1047,8 +1058,8 @@ typedef struct {
  * @union
  *
  * This union includes all frames to pass them to various function
- * calls as nghttp2_frame type. The CONTINUATION frame is omitted from
- * here because the library deals with it internally.
+ * calls as nghttp2_frame type.  The CONTINUATION frame is omitted
+ * from here because the library deals with it internally.
  */
 typedef union {
   /**
@@ -1105,15 +1116,15 @@ typedef union {
  * |length| bytes of data stored in |data|.  The |flags| 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 :enum:`NGHTTP2_ERR_WOULDBLOCK`. For other errors, it
- * must return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`. The |user_data|
- * pointer is the third argument passed in to the call to
+ * it must return :enum:`NGHTTP2_ERR_WOULDBLOCK`.  For other errors,
+ * it must return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`.  The
+ * |user_data| pointer is the third argument passed in to the call to
  * `nghttp2_session_client_new()` or `nghttp2_session_server_new()`.
  *
  * This callback is required if the application uses
  * `nghttp2_session_send()` to send data to the remote endpoint.  If
- * the application uses `nghttp2_session_mem_send()` instead, this
- * callback function is unnecessary.
+ * the application uses solely `nghttp2_session_mem_send()` instead,
+ * this callback function is unnecessary.
  */
 typedef ssize_t (*nghttp2_send_callback)
 (nghttp2_session *session,
@@ -1125,19 +1136,19 @@ typedef ssize_t (*nghttp2_send_callback)
  * Callback function invoked when |session| wants to receive data from
  * the remote peer.  The implementation of this function must read at
  * most |length| bytes of data and store it in |buf|.  The |flags| is
- * currently not used and always 0. It must return the number of bytes
- * written in |buf| if it succeeds. If it cannot read any single byte
- * without blocking, it must return :enum:`NGHTTP2_ERR_WOULDBLOCK`. If
- * it gets EOF before it reads any single byte, it must return
- * :enum:`NGHTTP2_ERR_EOF`. For other errors, it must return
- * :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`. Returning 0 is treated as
- * :enum:`NGHTTP2_ERR_WOULDBLOCK`. The |user_data| pointer is the
- * third argument passed in to the call to
+ * currently not used and always 0.  It must return the number of
+ * bytes written in |buf| if it succeeds.  If it cannot read any
+ * single byte without blocking, it must return
+ * :enum:`NGHTTP2_ERR_WOULDBLOCK`.  If it gets EOF before it reads any
+ * single byte, it must return :enum:`NGHTTP2_ERR_EOF`.  For other
+ * errors, it must return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`.
+ * Returning 0 is treated as :enum:`NGHTTP2_ERR_WOULDBLOCK`.  The
+ * |user_data| pointer is the third argument passed in to the call to
  * `nghttp2_session_client_new()` or `nghttp2_session_server_new()`.
  *
  * This callback is required if the application uses
- * `nghttp2_session_recv()` to receive data from the remote
- * endpoint. If the application uses `nghttp2_session_mem_recv()`
+ * `nghttp2_session_recv()` to receive data from the remote endpoint.
+ * If the application uses solely `nghttp2_session_mem_recv()`
  * instead, this callback function is unnecessary.
  */
 typedef ssize_t (*nghttp2_recv_callback)
@@ -1147,7 +1158,7 @@ typedef ssize_t (*nghttp2_recv_callback)
 /**
  * @functypedef
  *
- * Callback function invoked by `nghttp2_session_recv()` when a aframe
+ * Callback function invoked by `nghttp2_session_recv()` when a frame
  * is received.  The |user_data| pointer is the third argument passed
  * in to the call to `nghttp2_session_client_new()` or
  * `nghttp2_session_server_new()`.
@@ -1163,14 +1174,14 @@ typedef ssize_t (*nghttp2_recv_callback)
  * check that stream is still alive using its own stream management or
  * :func:`nghttp2_session_get_stream_user_data()`.
  *
- * Only HEADERS and DATA frame can signal the end of incoming data. If
- * ``frame->hd.flags & NGHTTP2_FLAG_END_STREAM`` is nonzero, the
+ * Only HEADERS and DATA frame can signal the end of incoming data.
+ * If ``frame->hd.flags & NGHTTP2_FLAG_END_STREAM`` is nonzero, the
  * |frame| is the last frame from the remote peer in this stream.
  *
- * The implementation of this function must return 0 if it
- * succeeds. If nonzero value is returned, it is treated as fatal
- * error and `nghttp2_session_recv()` and `nghttp2_session_mem_recv()`
- * functions immediately return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`.
+ * The implementation of this function must return 0 if it succeeds.
+ * If nonzero value is returned, it is treated as fatal error and
+ * `nghttp2_session_recv()` and `nghttp2_session_mem_recv()` functions
+ * immediately return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`.
  */
 typedef int (*nghttp2_on_frame_recv_callback)
 (nghttp2_session *session, const nghttp2_frame *frame, void *user_data);
@@ -1190,8 +1201,8 @@ typedef int (*nghttp2_on_frame_recv_callback)
  * member of their data structure are always ``NULL`` and 0
  * respectively.
  *
- * The implementation of this function must return 0 if it
- * succeeds. If nonzero is returned, it is treated as fatal error and
+ * The implementation of this function must return 0 if it succeeds.
+ * If nonzero is returned, it is treated as fatal error and
  * `nghttp2_session_recv()` and `nghttp2_session_send()` functions
  * immediately return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`.
  */
@@ -1204,25 +1215,25 @@ typedef int (*nghttp2_on_invalid_frame_recv_callback)
  *
  * Callback function invoked when a chunk of data in DATA frame is
  * received.  The |stream_id| is the stream ID this DATA frame belongs
- * to. The |flags| is the flags of DATA frame which this data chunk is
- * contained. ``(flags & NGHTTP2_FLAG_END_STREAM) != 0`` does not
- * necessarily mean this chunk of data is the last one in the
- * stream. You should use :type:`nghttp2_on_frame_recv_callback` to
- * know all data frames are received. The |user_data| pointer is the
- * third argument passed in to the call to
- * `nghttp2_session_client_new()` or `nghttp2_session_server_new()`.
+ * to.  The |flags| is the flags of DATA frame which this data chunk
+ * is contained.  ``(flags & NGHTTP2_FLAG_END_STREAM) != 0`` does not
+ * necessarily mean this chunk of data is the last one in the stream.
+ * You should use :type:`nghttp2_on_frame_recv_callback` to know all
+ * data frames are received.  The |user_data| pointer is the third
+ * argument passed in to the call to `nghttp2_session_client_new()` or
+ * `nghttp2_session_server_new()`.
  *
  * If the application uses `nghttp2_session_mem_recv()`, it can return
  * :enum:`NGHTTP2_ERR_PAUSE` to make `nghttp2_session_mem_recv()`
  * return without processing further input bytes.  The memory by
  * pointed by the |data| is retained until
- * `nghttp2_session_mem_recv()` or `nghttp2_session_recv()` is
- * called. The application must retain the input bytes which was used
- * to produce the |data| parameter, because it may refer to the memory
+ * `nghttp2_session_mem_recv()` or `nghttp2_session_recv()` is called.
+ * The application must retain the input bytes which was used to
+ * produce the |data| parameter, because it may refer to the memory
  * region included in the input bytes.
  *
- * The implementation of this function must return 0 if it
- * succeeds. If nonzero is returned, it is treated as fatal error and
+ * The implementation of this function must return 0 if it succeeds.
+ * If nonzero is returned, it is treated as fatal error and
  * `nghttp2_session_recv()` and `nghttp2_session_mem_recv()` functions
  * immediately return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`.
  */
@@ -1241,8 +1252,8 @@ typedef int (*nghttp2_on_data_chunk_recv_callback)
  * passed in to the call to `nghttp2_session_client_new()` or
  * `nghttp2_session_server_new()`.
  *
- * The implementation of this function must return 0 if it
- * succeeds. If nonzero is returned, it is treated as fatal error and
+ * The implementation of this function must return 0 if it succeeds.
+ * If nonzero is returned, it is treated as fatal error and
  * `nghttp2_session_recv()` and `nghttp2_session_send()` functions
  * immediately return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`.
  */
@@ -1256,8 +1267,8 @@ typedef int (*nghttp2_before_frame_send_callback)
  * |user_data| pointer is the third argument passed in to the call to
  * `nghttp2_session_client_new()` or `nghttp2_session_server_new()`.
  *
- * The implementation of this function must return 0 if it
- * succeeds. If nonzero is returned, it is treated as fatal error and
+ * The implementation of this function must return 0 if it succeeds.
+ * If nonzero is returned, it is treated as fatal error and
  * `nghttp2_session_recv()` and `nghttp2_session_send()` functions
  * immediately return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`.
  */
@@ -1274,8 +1285,8 @@ typedef int (*nghttp2_on_frame_send_callback)
  * argument passed in to the call to `nghttp2_session_client_new()` or
  * `nghttp2_session_server_new()`.
  *
- * The implementation of this function must return 0 if it
- * succeeds. If nonzero is returned, it is treated as fatal error and
+ * The implementation of this function must return 0 if it succeeds.
+ * If nonzero is returned, it is treated as fatal error and
  * `nghttp2_session_recv()` and `nghttp2_session_send()` functions
  * immediately return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`.
  */
@@ -1286,16 +1297,18 @@ typedef int (*nghttp2_on_frame_not_send_callback)
 /**
  * @functypedef
  *
- * Callback function invoked when the stream |stream_id| is
- * closed. The reason of closure is indicated by the |error_code|. The
+ * Callback function invoked when the stream |stream_id| is closed.
+ * The reason of closure is indicated by the |error_code|.  The
  * stream_user_data, which was specified in `nghttp2_submit_request()`
- * or `nghttp2_submit_headers()`, is still available in this
- * function. The |user_data| pointer is the third argument passed in
- * to the call to `nghttp2_session_client_new()` or
+ * or `nghttp2_submit_headers()`, is still available in this function.
+ * The |user_data| pointer is the third argument passed in to the call
+ * to `nghttp2_session_client_new()` or
  * `nghttp2_session_server_new()`.
  *
- * The implementation of this function must return 0 if it
- * succeeds. If nonzero is returned, it is treated as fatal error and
+ * This function is also called for a stream in reserved state.
+ *
+ * The implementation of this function must return 0 if it succeeds.
+ * If nonzero is returned, it is treated as fatal error and
  * `nghttp2_session_recv()` and `nghttp2_session_send()` functions
  * immediately return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`.
  */
@@ -1306,19 +1319,18 @@ typedef int (*nghttp2_on_stream_close_callback)
 /**
  * @functypedef
  *
- * Callback function invoked when the received frame type is
- * unknown. The |head| is the pointer to the header of the received
- * frame. The |headlen| is the length of the |head|. According to the
- * spec, the |headlen| is always 8. In other words, the |head| is the
- * first 8 bytes of the received frame.  The |payload| is the pointer
- * to the data portion of the received frame.  The |payloadlen| is the
- * length of the |payload|. This is the data after the length
- * field. The |user_data| pointer is the third argument passed in to
- * the call to `nghttp2_session_client_new()` or
- * `nghttp2_session_server_new()`.
+ * Callback function invoked when the received frame type is unknown.
+ * The |head| is the pointer to the header of the received frame.  The
+ * |headlen| is the length of the |head|.  According to the spec, the
+ * |headlen| is always 8.  In other words, the |head| is the first 8
+ * bytes of the received frame.  The |payload| is the pointer to the
+ * data portion of the received frame.  The |payloadlen| is the length
+ * of the |payload|.  This is the data after the length field.  The
+ * |user_data| pointer is the third argument passed in to the call to
+ * `nghttp2_session_client_new()` or `nghttp2_session_server_new()`.
  *
- * The implementation of this function must return 0 if it
- * succeeds. If nonzero is returned, it is treated as fatal error and
+ * The implementation of this function must return 0 if it succeeds.
+ * If nonzero is returned, it is treated as fatal error and
  * `nghttp2_session_recv()` and `nghttp2_session_send()` functions
  * immediately return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`.
  */
@@ -1393,18 +1405,18 @@ typedef int (*nghttp2_on_begin_headers_callback)
  * :enum:`NGHTTP2_ERR_PAUSE` to make `nghttp2_session_mem_recv()`
  * return without processing further input bytes.  The memory pointed
  * by |frame|, |name| and |value| parameters are retained until
- * `nghttp2_session_mem_recv()` or `nghttp2_session_recv()` is
- * called. The application must retain the input bytes which was used
- * to produce these parameters, because it may refer to the memory
- * region included in the input bytes.
+ * `nghttp2_session_mem_recv()` or `nghttp2_session_recv()` is called.
+ * The application must retain the input bytes which was used to
+ * produce these parameters, because it may refer to the memory region
+ * included in the input bytes.
  *
  * Returning :enum:`NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE` will close
  * the stream by issuing RST_STREAM with
  * :enum:`NGHTTP2_INTERNAL_ERROR`.  In this case,
  * :type:`nghttp2_on_frame_recv_callback` will not be invoked.
  *
- * The implementation of this function must return 0 if it
- * succeeds. It may return :enum:`NGHTTP2_ERR_PAUSE` or
+ * The implementation of this function must return 0 if it succeeds.
+ * It may return :enum:`NGHTTP2_ERR_PAUSE` or
  * :enum:`NGHTTP2_ERR_TEMPORAL_CALLBACK_FAILURE`.  For other critical
  * failures, it must return :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`.  If
  * the other nonzero value is returned, it is treated as
@@ -1425,9 +1437,9 @@ typedef int (*nghttp2_on_header_callback)
  * @functypedef
  *
  * Callback function invoked when the library asks application how
- * much padding is required for the transmission of the |frame|. The
- * application must choose the total length of payload including
- * padded bytes in range [frame->hd.length, max_payloadlen],
+ * many padding bytes are required for the transmission of the
+ * |frame|.  The application must choose the total length of payload
+ * including padded bytes in range [frame->hd.length, max_payloadlen],
  * inclusive.  Choosing number not in this range will be treated as
  * :enum:`NGHTTP2_ERR_CALLBACK_FAILURE`.  Returning
  * ``frame->hd.length`` means no padding is added.  Returning
@@ -1450,15 +1462,15 @@ typedef struct {
   /**
    * Callback function invoked when the |session| wants to send data
    * to the remote peer.  This callback is not necessary if the
-   * application uses `nghttp2_session_mem_send()` to serialize data
-   * to transmit.
+   * application uses solely `nghttp2_session_mem_send()` to serialize
+   * data to transmit.
    */
   nghttp2_send_callback send_callback;
   /**
    * Callback function invoked when the |session| wants to receive
    * data from the remote peer.  This callback is not necessary if the
-   * application uses `nghttp2_session_mem_recv()` to process received
-   * data.
+   * application uses solely `nghttp2_session_mem_recv()` to process
+   * received data.
    */
   nghttp2_recv_callback recv_callback;
   /**
@@ -1510,7 +1522,8 @@ typedef struct {
   nghttp2_on_header_callback on_header_callback;
   /**
    * Callback function invoked when the library asks application how
-   * much padding is required for the transmission of the given frame.
+   * many padding bytes are required for the transmission of the given
+   * frame.
    */
   nghttp2_select_padding_callback select_padding_callback;
 } nghttp2_session_callbacks;
@@ -1568,9 +1581,9 @@ void nghttp2_option_set_no_auto_stream_window_update(nghttp2_option *option,
  * This option prevents the library from sending WINDOW_UPDATE for a
  * connection automatically.  If this option is set to nonzero, the
  * library won't send WINDOW_UPDATE for a connection and the
- * application is responsible for sending WINDOW_UPDATE with stream
- * ID 0 using `nghttp2_submit_window_update`. By default, this
- * option is set to zero.
+ * application is responsible for sending WINDOW_UPDATE with stream ID
+ * 0 using `nghttp2_submit_window_update`.  By default, this option is
+ * set to zero.
  */
 void nghttp2_option_set_no_auto_connection_window_update
 (nghttp2_option *option, int val);
@@ -1583,11 +1596,11 @@ void nghttp2_option_set_no_auto_connection_window_update
  * 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
- * initially and sending them at once to the remote peer may lead to
- * the rejection of some requests. Specifying this option to the
- * sensible value, say 100, may avoid this kind of issue. This value
- * will be overwritten if the local endpoint receives
+ * cause problem if local endpoint submits lots of requests initially
+ * and sending them at once to the remote peer may lead to the
+ * rejection of some requests.  Specifying this option to the sensible
+ * value, say 100, may avoid this kind of issue. This value will be
+ * overwritten if the local endpoint receives
  * SETTINGS_MAX_CONCURRENT_STREAMS from the remote endpoint.
  */
 void nghttp2_option_set_peer_max_concurrent_streams(nghttp2_option *option,
@@ -1598,7 +1611,7 @@ void nghttp2_option_set_peer_max_concurrent_streams(nghttp2_option *option,
  *
  * Initializes |*session_ptr| for client use.  The all members of
  * |callbacks| are copied to |*session_ptr|.  Therefore |*session_ptr|
- * does not store |callbacks|. |user_data| is an arbitrary user
+ * does not store |callbacks|.  The |user_data| is an arbitrary user
  * supplied data, which will be passed to the callback functions.
  *
  * The :member:`nghttp2_session_callbacks.send_callback` must be
@@ -1621,7 +1634,7 @@ int nghttp2_session_client_new(nghttp2_session **session_ptr,
  *
  * Initializes |*session_ptr| for server use.  The all members of
  * |callbacks| are copied to |*session_ptr|. Therefore |*session_ptr|
- * does not store |callbacks|. |user_data| is an arbitrary user
+ * does not store |callbacks|.  The |user_data| is an arbitrary user
  * supplied data, which will be passed to the callback functions.
  *
  * The :member:`nghttp2_session_callbacks.send_callback` must be
@@ -1716,19 +1729,20 @@ void nghttp2_session_del(nghttp2_session *session);
  * 1. Get the next frame to send from outbound queue.
  * 2. Prepare transmission of the frame.
  * 3. If the control frame cannot be sent because some preconditions
- *    are not met (e.g., request HEADERS cannot be sent after
- *    GOAWAY),
- *    :member:`nghttp2_session_callbacks.on_frame_not_send_callback` is
- *    invoked. Abort the following steps.
- * 4. If the frame is request HEADERS, the stream is opened
- *    here.
- * 5. :member:`nghttp2_session_callbacks.before_frame_send_callback` is
+ *    are not met (e.g., request HEADERS cannot be sent after GOAWAY),
+ *    :member:`nghttp2_session_callbacks.on_frame_not_send_callback`
+ *    is invoked.  Abort the following steps.
+ * 4. If the frame is HEADERS, PUSH_PROMISE or DATA,
+ *    :member:`nghttp2_session_callbacks.select_padding_callback` is
  *    invoked.
- * 6. :member:`nghttp2_session_callbacks.send_callback` is invoked one
+ * 5. If the frame is request HEADERS, the stream is opened here.
+ * 6. :member:`nghttp2_session_callbacks.before_frame_send_callback` is
+ *    invoked.
+ * 7. :member:`nghttp2_session_callbacks.send_callback` is invoked one
  *    or more times to send the frame.
- * 7. :member:`nghttp2_session_callbacks.on_frame_send_callback` is
+ * 8. :member:`nghttp2_session_callbacks.on_frame_send_callback` is
  *    invoked.
- * 8. If the transmission of the frame triggers closure of the stream,
+ * 9. If the transmission of the frame triggers closure of the stream,
  *    the stream is closed and
  *    :member:`nghttp2_session_callbacks.on_stream_close_callback` is
  *    invoked.
@@ -1748,17 +1762,18 @@ int nghttp2_session_send(nghttp2_session *session);
  *
  * Returns the serialized data to send.
  *
- * This function behaves like `nghttp2_session_send()` except that
- * it does not use :member:`nghttp2_session_callbacks.send_callback`
- * to transmit data. Instead, it assigns the pointer to the serialized
- * data to the |*data_ptr| and returns its length. The other callbacks
- * are called in the same way as they are in `nghttp2_session_send()`.
+ * This function behaves like `nghttp2_session_send()` except that it
+ * does not use :member:`nghttp2_session_callbacks.send_callback` to
+ * transmit data.  Instead, it assigns the pointer to the serialized
+ * data to the |*data_ptr| and returns its length.  The other
+ * callbacks are called in the same way as they are in
+ * `nghttp2_session_send()`.
  *
  * If no data is available to send, this function returns 0.
  *
- * This function may not return all serialized data in one
- * invocation. To get all data, call this function repeatedly until it
- * returns 0 or one of negative error codes.
+ * This function may not return all serialized data in one invocation.
+ * To get all data, call this function repeatedly until it returns 0
+ * or one of negative error codes.
  *
  * The assigned |*data_ptr| is valid until the next call of
  * `nghttp2_session_mem_send()` or `nghttp2_session_send()`.
@@ -1936,8 +1951,8 @@ void* nghttp2_session_get_stream_user_data(nghttp2_session *session,
  * @function
  *
  * Sets the |stream_user_data| to the stream denoted by the
- * |stream_id|. If a stream user data is already set to the stream, it
- * is replaced with the |stream_user_data|. It is valid to specify
+ * |stream_id|.  If a stream user data is already set to the stream,
+ * it is replaced with the |stream_user_data|.  It is valid to specify
  * ``NULL`` in the |stream_user_data|, which nullifies the associated
  * data pointer.
  *
@@ -1982,8 +1997,8 @@ int32_t nghttp2_session_get_stream_effective_recv_data_length
 /**
  * @function
  *
- * Returns the local (receive) window size for the stream
- * |stream_id|. The local window size can be adjusted by
+ * Returns the local (receive) window size for the stream |stream_id|.
+ * The local window size can be adjusted by
  * `nghttp2_submit_window_update()`.  This function takes into account
  * that and returns effective window size.
  *
@@ -1997,12 +2012,12 @@ int32_t nghttp2_session_get_stream_effective_local_window_size
  *
  * 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
- * `nghttp2_submit_window_update()`. This function takes into account
- * that and returns effective data length. In particular, if the local
- * window size is reduced by submitting negative window_size_increment
- * with `nghttp2_submit_window_update()`, this function returns the
- * number of bytes less than actually received.
+ * window size can be adjusted by `nghttp2_submit_window_update()`.
+ * This function takes into account that and returns effective data
+ * length.  In particular, if the local window size is reduced by
+ * submitting negative window_size_increment with
+ * `nghttp2_submit_window_update()`, this function returns the number
+ * of bytes less than actually received.
  *
  * This function returns -1 if it fails.
  */
@@ -2012,8 +2027,8 @@ int32_t nghttp2_session_get_effective_recv_data_length
 /**
  * @function
  *
- * Returns the local (receive) window size for a connection. The local
- * window size can be adjusted by
+ * Returns the local (receive) window size for a connection.  The
+ * local window size can be adjusted by
  * `nghttp2_submit_window_update()`.  This function takes into account
  * that and returns effective window size.
  *
@@ -2048,8 +2063,8 @@ int32_t nghttp2_session_get_stream_remote_window_size(nghttp2_session* session,
  * function succeeds.
  *
  * This function should be called when the connection should be
- * terminated after sending GOAWAY. If the remaining streams should be
- * processed after GOAWAY, use `nghttp2_submit_goaway()` instead.
+ * terminated after sending GOAWAY.  If the remaining streams should
+ * be processed after GOAWAY, use `nghttp2_submit_goaway()` instead.
  *
  * This function returns 0 if it succeeds, or one of the following
  * negative error codes:
@@ -2063,20 +2078,19 @@ int nghttp2_session_terminate_session(nghttp2_session *session,
 /**
  * @function
  *
- * Performs post-process of HTTP Upgrade request. This function can be
- * called from both client and server, but the behavior is very
+ * Performs post-process of HTTP Upgrade request.  This function can
+ * be called from both client and server, but the behavior is very
  * different in each other.
  *
  * If called from client side, the |settings_payload| must be the
  * value sent in ``HTTP2-Settings`` header field and must be decoded
  * by base64url decoder.  The |settings_payloadlen| is the length of
  * |settings_payload|.  The |settings_payload| is unpacked and its
- * setting values will be submitted using
- * `nghttp2_submit_settings()`. This means that the client application
- * code does not need to submit SETTINGS by itself. The stream with
- * stream ID=1 is opened and the |stream_user_data| is used for its
- * stream_user_data. The opened stream becomes half-closed (local)
- * state.
+ * setting values will be submitted using `nghttp2_submit_settings()`.
+ * This means that the client application code does not need to submit
+ * SETTINGS by itself.  The stream with stream ID=1 is opened and the
+ * |stream_user_data| is used for its stream_user_data.  The opened
+ * stream becomes half-closed (local) state.
  *
  * If called from server side, the |settings_payload| must be the
  * value received in ``HTTP2-Settings`` header field and must be
@@ -2208,8 +2222,8 @@ void nghttp2_priority_spec_dep_init(nghttp2_priority_spec *pri_spec,
  * 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
- * :member:`nghttp2_session_callbacks.before_frame_send_callback`. This
- * callback is called just before the frame is sent. For HEADERS
+ * :member:`nghttp2_session_callbacks.before_frame_send_callback`.
+ * 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,
  * `nghttp2_session_get_stream_user_data()` can be used to get
@@ -2220,6 +2234,8 @@ void nghttp2_priority_spec_dep_init(nghttp2_priority_spec *pri_spec,
  *
  * :enum:`NGHTTP2_ERR_NOMEM`
  *     Out of memory.
+ * :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`
+ *     The |pri_spec->pri_type| is invalid.
  */
 int nghttp2_submit_request(nghttp2_session *session,
                            const nghttp2_priority_spec *pri_spec,
@@ -2252,11 +2268,11 @@ int nghttp2_submit_request(nghttp2_session *session,
  * |data_prd|.  If |data_prd| is ``NULL``, HEADERS will have
  * END_STREAM flag set.
  *
- * This method can be used as normal HTTP response and push
- * response. When pushing a resource using this function, the
- * |session| must be configured using `nghttp2_session_server_new()`
- * or its variants and the target stream denoted by the |stream_id|
- * must be reserved using `nghttp2_submit_push_promise()`.
+ * This method can be used as normal HTTP response and push response.
+ * When pushing a resource using this function, the |session| must be
+ * configured using `nghttp2_session_server_new()` or its variants and
+ * the target stream denoted by the |stream_id| must be reserved using
+ * `nghttp2_submit_push_promise()`.
  *
  * This function returns 0 if it succeeds, or one of the following
  * negative error codes:
@@ -2307,9 +2323,9 @@ int nghttp2_submit_response(nghttp2_session *session,
  * also lower-cases all names in |nva|.
  *
  * The |stream_user_data| is a pointer to an arbitrary data which is
- * associated to the stream this frame will open. Therefore it is only
- * used if this frame opens streams, in other words, it changes stream
- * state from idle or reserved to open.
+ * associated to the stream this frame will open.  Therefore it is
+ * only used if this frame opens streams, in other words, it changes
+ * stream state from idle or reserved to open.
  *
  * This function is low-level in a sense that the application code can
  * specify flags directly.  For usual HTTP request,
@@ -2320,6 +2336,8 @@ int nghttp2_submit_response(nghttp2_session *session,
  *
  * :enum:`NGHTTP2_ERR_NOMEM`
  *     Out of memory.
+ * :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`
+ *     The |pri_spec->pri_type| is invalid.
  */
 int nghttp2_submit_headers(nghttp2_session *session, uint8_t flags,
                            int32_t stream_id,
@@ -2333,8 +2351,8 @@ int nghttp2_submit_headers(nghttp2_session *session, uint8_t flags,
  * Submits one or more DATA frames to the stream |stream_id|.  The
  * data to be sent are provided by |data_prd|.  If |flags| contains
  * :enum:`NGHTTP2_FLAG_END_STREAM`, the last DATA frame has END_STREAM
- * flag set. If |flags| contains :enum:`NGHTTP2_FLAG_END_SEGMENT`, the
- * last DATA frame has END_SEGMENT flag set.
+ * flag set.  If |flags| contains :enum:`NGHTTP2_FLAG_END_SEGMENT`,
+ * the last DATA frame has END_SEGMENT flag set.
  *
  * This function does not take ownership of the |data_prd|.  The
  * function copies the members of the |data_prd|.
@@ -2372,7 +2390,8 @@ int nghttp2_submit_data(nghttp2_session *session, uint8_t flags,
  * :enum:`NGHTTP2_ERR_NOMEM`
  *     Out of memory.
  * :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`
- *     The |pri_spec| is NULL; or trying to depend on itself.
+ *     The |pri_spec| is NULL; or the |pri_spec->pri_type| is invalid;
+ *     or trying to depend on itself.
  */
 int nghttp2_submit_priority(nghttp2_session *session, uint8_t flags,
                             int32_t stream_id,
@@ -2467,18 +2486,21 @@ int nghttp2_submit_settings(nghttp2_session *session, uint8_t flags,
  * 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
- * :member:`nghttp2_session_callbacks.before_frame_send_callback`. This
- * callback is called just before the frame is sent. For PUSH_PROMISE
- * frame, the argument frame has the promised stream ID assigned.
+ * :member:`nghttp2_session_callbacks.before_frame_send_callback`.
+ * This callback is called just before the frame is sent.  For
+ * PUSH_PROMISE frame, the argument frame has the promised stream ID
+ * assigned.
  *
- * The client side can use this function to send PUSH_PROMISE to the
- * server. But in normal HTTP usage, the server may treat it error.
+ * The client side is not allowed to use this function.
  *
  * This function returns 0 if it succeeds, or one of the following
  * negative error codes:
  *
  * :enum:`NGHTTP2_ERR_NOMEM`
  *     Out of memory.
+ * :enum:`NGHTTP2_ERR_PROTO`
+ *     This function was invoked when |session| is initialized as
+ *     client.
  */
 int nghttp2_submit_push_promise(nghttp2_session *session, uint8_t flags,
                                 int32_t stream_id,
@@ -2596,7 +2618,7 @@ int nghttp2_submit_window_update(nghttp2_session *session, uint8_t flags,
  *
  * :enum:`NGHTTP2_ERR_NOMEM`
  *     Out of memory.
- * :enum:`NGHTTP2_ERR_INVALID_STATE`
+ * :enum:`NGHTTP2_ERR_PROTO`
  *     The function is invoked with |session| which was initialized as
  *     client.
  * :enum:`NGHTTP2_ERR_INVALID_ARGUMENT`
@@ -2613,10 +2635,11 @@ int nghttp2_submit_altsvc(nghttp2_session *session, uint8_t flags,
 /**
  * @function
  *
- * Compares lhs->name with lhs->namelen bytes and rhs->name with
- * rhs->namelen bytes. Returns negative integer if lhs->name is found
- * to be less than rhs->name; or returns positive integer if lhs->name
- * is found to be greater than rhs->name; or returns 0 otherwise.
+ * Compares ``lhs->name`` of length ``lhs->namelen`` bytes and
+ * ``rhs->name`` of length ``rhs->namelen`` bytes.  Returns negative
+ * integer if ``lhs->name`` is found to be less than ``rhs->name``; or
+ * returns positive integer if ``lhs->name`` is found to be greater
+ * than ``rhs->name``; or returns 0 otherwise.
  */
 int nghttp2_nv_compare_name(const nghttp2_nv *lhs, const nghttp2_nv *rhs);
 
@@ -2643,16 +2666,16 @@ int nghttp2_nv_compare_name(const nghttp2_nv *lhs, const nghttp2_nv *rhs);
  * 2. If peer's list contains ``http/1.1``, this function selects
  *    ``http/1.1`` and returns 0.  The following step is not taken.
  *
- * 3. This function selects nothing and returns -1. (So called
+ * 3. This function selects nothing and returns -1 (So called
  *    non-overlap case).  In this case, |out| and |outlen| are left
  *    untouched.
  *
  * Selecting ``HTTP-draft-04/2.0`` means that ``HTTP-draft-04/2.0`` is
- * written into |*out| and its length (which is 17) is
- * assigned to |*outlen|.
+ * written into |*out| and its length (which is 17) is assigned to
+ * |*outlen|.
  *
  * For ALPN, refer to
- * http://tools.ietf.org/html/draft-ietf-tls-applayerprotoneg-04
+ * https://tools.ietf.org/html/draft-ietf-tls-applayerprotoneg-05
  *
  * See http://technotes.googlecode.com/git/nextprotoneg.html for more
  * details about NPN.
@@ -2693,7 +2716,8 @@ typedef struct nghttp2_gzip nghttp2_gzip;
 /**
  * @function
  *
- * A helper function to set up a per request gzip stream to inflate data.
+ * A helper function to set up a per request gzip stream to inflate
+ * data.
  *
  * This function returns 0 if it succeeds, or one of the following
  * negative error codes:
@@ -2763,11 +2787,11 @@ int nghttp2_gzip_inflate(nghttp2_gzip *inflater,
 /**
  * @function
  *
- * Returns a pointer to a nghttp2_info struct with version information about
- * the run-time library in use.  The |least_version| argument can be set to a
- * 24 bit numerical value for the least accepted version number and if the
- * condition is not met, this function will return a NULL. Pass in 0 to skip
- * the version checking.
+ * Returns a pointer to a nghttp2_info struct with version information
+ * about the run-time library in use.  The |least_version| argument
+ * can be set to a 24 bit numerical value for the least accepted
+ * version number and if the condition is not met, this function will
+ * return a ``NULL``.  Pass in 0 to skip the version checking.
  */
 nghttp2_info *nghttp2_version(int least_version);