source-git / nghttp2

Clone
Source Code
GIT

Files

c8 c8s master
  1.   c8s
  2.   doc
_exts
_themes
bash_completion
sources
CMakeLists.txt
Makefile.am
Makefile.in
README.rst
asio_http2.h.rst.in
asio_http2_client.h.rst.in
asio_http2_server.h.rst.in
building-android-binary.rst.in
conf.py.in
contribute.rst.in
enums.rst
h2load-howto.rst.in
h2load.1
h2load.1.rst
index.rst.in
libnghttp2_asio.rst.in
macros.rst
nghttp.1
nghttp.1.rst
nghttp2.h.rst.in
nghttp2_check_header_name.rst
nghttp2_check_header_value.rst
nghttp2_hd_deflate_bound.rst
nghttp2_hd_deflate_change_table_size.rst
nghttp2_hd_deflate_del.rst
nghttp2_hd_deflate_get_dynamic_table_size.rst
nghttp2_hd_deflate_get_max_dynamic_table_size.rst
nghttp2_hd_deflate_get_num_table_entries.rst
nghttp2_hd_deflate_get_table_entry.rst
nghttp2_hd_deflate_hd.rst
nghttp2_hd_deflate_hd_vec.rst
nghttp2_hd_deflate_new.rst
nghttp2_hd_deflate_new2.rst
nghttp2_hd_inflate_change_table_size.rst
nghttp2_hd_inflate_del.rst
nghttp2_hd_inflate_end_headers.rst
nghttp2_hd_inflate_get_dynamic_table_size.rst
nghttp2_hd_inflate_get_max_dynamic_table_size.rst
nghttp2_hd_inflate_get_num_table_entries.rst
nghttp2_hd_inflate_get_table_entry.rst
nghttp2_hd_inflate_hd.rst
nghttp2_hd_inflate_hd2.rst
nghttp2_hd_inflate_new.rst
nghttp2_hd_inflate_new2.rst
nghttp2_http2_strerror.rst
nghttp2_is_fatal.rst
nghttp2_nv_compare_name.rst
nghttp2_option_del.rst
nghttp2_option_new.rst
nghttp2_option_set_builtin_recv_extension_type.rst
nghttp2_option_set_max_deflate_dynamic_table_size.rst
nghttp2_option_set_max_reserved_remote_streams.rst
nghttp2_option_set_max_send_header_block_length.rst
nghttp2_option_set_no_auto_ping_ack.rst
nghttp2_option_set_no_auto_window_update.rst
nghttp2_option_set_no_closed_streams.rst
nghttp2_option_set_no_http_messaging.rst
nghttp2_option_set_no_recv_client_magic.rst
nghttp2_option_set_peer_max_concurrent_streams.rst
nghttp2_option_set_user_recv_extension_type.rst
nghttp2_pack_settings_payload.rst
nghttp2_priority_spec_check_default.rst
nghttp2_priority_spec_default_init.rst
nghttp2_priority_spec_init.rst
nghttp2_rcbuf_decref.rst
nghttp2_rcbuf_get_buf.rst
nghttp2_rcbuf_incref.rst
nghttp2_rcbuf_is_static.rst
nghttp2_select_next_protocol.rst
nghttp2_session_callbacks_del.rst
nghttp2_session_callbacks_new.rst
nghttp2_session_callbacks_set_before_frame_send_callback.rst
nghttp2_session_callbacks_set_data_source_read_length_callback.rst
nghttp2_session_callbacks_set_error_callback.rst
nghttp2_session_callbacks_set_error_callback2.rst
nghttp2_session_callbacks_set_on_begin_frame_callback.rst
nghttp2_session_callbacks_set_on_begin_headers_callback.rst
nghttp2_session_callbacks_set_on_data_chunk_recv_callback.rst
nghttp2_session_callbacks_set_on_extension_chunk_recv_callback.rst
nghttp2_session_callbacks_set_on_frame_not_send_callback.rst
nghttp2_session_callbacks_set_on_frame_recv_callback.rst
nghttp2_session_callbacks_set_on_frame_send_callback.rst
nghttp2_session_callbacks_set_on_header_callback.rst
nghttp2_session_callbacks_set_on_header_callback2.rst
nghttp2_session_callbacks_set_on_invalid_frame_recv_callback.rst
nghttp2_session_callbacks_set_on_invalid_header_callback.rst
nghttp2_session_callbacks_set_on_invalid_header_callback2.rst
nghttp2_session_callbacks_set_on_stream_close_callback.rst
nghttp2_session_callbacks_set_pack_extension_callback.rst
nghttp2_session_callbacks_set_recv_callback.rst
nghttp2_session_callbacks_set_select_padding_callback.rst
nghttp2_session_callbacks_set_send_callback.rst
nghttp2_session_callbacks_set_send_data_callback.rst
nghttp2_session_callbacks_set_unpack_extension_callback.rst
nghttp2_session_change_stream_priority.rst
nghttp2_session_check_request_allowed.rst
nghttp2_session_check_server_session.rst
nghttp2_session_client_new.rst
nghttp2_session_client_new2.rst
nghttp2_session_client_new3.rst
nghttp2_session_consume.rst
nghttp2_session_consume_connection.rst
nghttp2_session_consume_stream.rst
nghttp2_session_create_idle_stream.rst
nghttp2_session_del.rst
nghttp2_session_find_stream.rst
nghttp2_session_get_effective_local_window_size.rst
nghttp2_session_get_effective_recv_data_length.rst
nghttp2_session_get_hd_deflate_dynamic_table_size.rst
nghttp2_session_get_hd_inflate_dynamic_table_size.rst
nghttp2_session_get_last_proc_stream_id.rst
nghttp2_session_get_local_settings.rst
nghttp2_session_get_local_window_size.rst
nghttp2_session_get_next_stream_id.rst
nghttp2_session_get_outbound_queue_size.rst
nghttp2_session_get_remote_settings.rst
nghttp2_session_get_remote_window_size.rst
nghttp2_session_get_root_stream.rst
nghttp2_session_get_stream_effective_local_window_size.rst
nghttp2_session_get_stream_effective_recv_data_length.rst
nghttp2_session_get_stream_local_close.rst
nghttp2_session_get_stream_local_window_size.rst
nghttp2_session_get_stream_remote_close.rst
nghttp2_session_get_stream_remote_window_size.rst
nghttp2_session_get_stream_user_data.rst
nghttp2_session_mem_recv.rst
nghttp2_session_mem_send.rst
nghttp2_session_recv.rst
nghttp2_session_resume_data.rst
nghttp2_session_send.rst
nghttp2_session_server_new.rst
nghttp2_session_server_new2.rst
nghttp2_session_server_new3.rst
nghttp2_session_set_local_window_size.rst
nghttp2_session_set_next_stream_id.rst
nghttp2_session_set_stream_user_data.rst
nghttp2_session_set_user_data.rst
nghttp2_session_terminate_session.rst
nghttp2_session_terminate_session2.rst
nghttp2_session_upgrade.rst
nghttp2_session_upgrade2.rst
nghttp2_session_want_read.rst
nghttp2_session_want_write.rst
nghttp2_set_debug_vprintf_callback.rst
nghttp2_stream_get_first_child.rst
nghttp2_stream_get_next_sibling.rst
nghttp2_stream_get_parent.rst
nghttp2_stream_get_previous_sibling.rst
nghttp2_stream_get_state.rst
nghttp2_stream_get_sum_dependency_weight.rst
nghttp2_stream_get_weight.rst
nghttp2_strerror.rst
nghttp2_submit_altsvc.rst
nghttp2_submit_data.rst
nghttp2_submit_extension.rst
nghttp2_submit_goaway.rst
nghttp2_submit_headers.rst
nghttp2_submit_origin.rst
nghttp2_submit_ping.rst
nghttp2_submit_priority.rst
nghttp2_submit_push_promise.rst
nghttp2_submit_request.rst
nghttp2_submit_response.rst
nghttp2_submit_rst_stream.rst
nghttp2_submit_settings.rst
nghttp2_submit_shutdown_notice.rst
nghttp2_submit_trailer.rst
nghttp2_submit_window_update.rst
nghttp2_version.rst
nghttp2ver.h.rst.in
nghttpd.1
nghttpd.1.rst
nghttpx-howto.rst.in
nghttpx.1
nghttpx.1.rst
package_README.rst.in
programmers-guide.rst
python-apiref.rst.in
tutorial-client.rst.in
tutorial-hpack.rst.in
tutorial-server.rst.in
types.rst
mkapiref.py
README.rst

nghttp2 Documentation

The documentation of nghttp2 is generated using Sphinx. This directory contains the source files to be processed by Sphinx. The source file for API reference is generated using a script called mkapiref.py from the nghttp2 C source code.

Generating API reference

As described earlier, we use mkapiref.py to generate rst formatted text of API reference from C source code. The mkapiref.py is not so flexible and it requires that C source code is formatted in rather strict rules.

To generate API reference, just run make html. It runs mkapiref.py and then run Sphinx to build the entire document.

The mkapiref.py reads C source code and searches the comment block starts with /**. In other words, it only processes the comment block starting /**. The comment block must end with */. The mkapiref.py requires that which type of the object this comment block refers to. To specify the type of the object, the next line must contain the so-called action keyword. Currently, the following action keywords are supported: @function, @functypedef, @enum, @struct and @union. The following sections describes each action keyword.

@function

@function is used to refer to the function. The comment block is used for the document for the function. After the script sees the end of the comment block, it consumes the lines as the function declaration until the line which ends with ; is encountered.

In Sphinx doc, usually the function argument is formatted like *this*. But in C, * is used for dereferencing a pointer and we must escape * with a back slash. To avoid this, we format the argument like |this|. The mkapiref.py translates it with *this*, as escaping * inside | and | as necessary. Note that this shadows the substitution feature of Sphinx.

The example follows:

/**
 * @function
 *
 * Submits PING frame to the |session|.
 */
int nghttp2_submit_ping(nghttp2_session *session);

@functypedef

@functypedef is used to refer to the typedef of the function pointer. The formatting rule is pretty much the same with @function, but this outputs type domain, rather than function domain.

The example follows:

/**
 * @functypedef
 *
 * Callback function invoked when |session| wants to send data to
 * remote peer.
 */
typedef ssize_t (*nghttp2_send_callback)
(nghttp2_session *session,
 const uint8_t *data, size_t length, int flags, void *user_data);

@enum

@enum is used to refer to the enum. Currently, only enum typedefs are supported. The comment block is used for the document for the enum type itself. To document each values, put comment block starting with the line /** and ending with the */ just before the enum value. When the line starts with } is encountered, the mkapiref.py extracts strings next to } as the name of enum.

At the time of this writing, Sphinx does not support enum type. So we use type domain for enum it self and macro domain for each value. To refer to the enum value, use :enum: pseudo role. The mkapiref.py replaces it with :macro:. By doing this, when Sphinx will support enum officially, we can replace :enum: with the official role easily.

The example follows:

/**
 * @enum
 * Error codes used in the nghttp2 library.
 */
typedef enum {
  /**
   * Invalid argument passed.
   */
  NGHTTP2_ERR_INVALID_ARGUMENT = -501,
  /**
   * Zlib error.
   */
  NGHTTP2_ERR_ZLIB = -502,
} nghttp2_error;

@struct

@struct is used to refer to the struct. Currently, only struct typedefs are supported. The comment block is used for the document for the struct type itself.To document each member, put comment block starting with the line /** and ending with the */ just before the member. When the line starts with } is encountered, the mkapiref.py extracts strings next to } as the name of struct. The block-less typedef is also supported. In this case, typedef declaration must be all in one line and the mkapiref.py uses last word as the name of struct.

Some examples follow:

/**
 * @struct
 * The control frame header.
 */
typedef struct {
  /**
   * SPDY protocol version.
   */
  uint16_t version;
  /**
   * The type of this control frame.
   */
  uint16_t type;
  /**
   * The control frame flags.
   */
  uint8_t flags;
  /**
   * The length field of this control frame.
   */
  int32_t length;
} nghttp2_ctrl_hd;

/**
 * @struct
 *
 * The primary structure to hold the resources needed for a SPDY
 * session. The details of this structure is hidden from the public
 * API.
 */
typedef struct nghttp2_session nghttp2_session;

@union

@union is used to refer to the union. Currently, @union is an alias of @struct.

Powered by Pagure 5.13.3

SSH Hostkey/Fingerprint | Documentation