nghttp2/doc
Tatsuhiro Tsujikawa 9eff511c5e Add nghttp2_send_data_callback to send DATA payload without copying
To avoid buffer copy in nghttp2_data_source_read_callback, this commit
introduces NGHTTP2_DATA_FLAG_NO_COPY and nghttp2_send_data_callback.
By using NGHTTP2_DATA_FLAG_NO_COPY in
nghttp2_data_source_read_callback, application can avoid to copy
application data to given buffer.  Instead, application has to
implement nghttp2_send_data_callback to send complete DATA frame by
itself.  We see noticeable performance increase in nghttpd and
tiny-nghttpd using this new feature.  On the other hand, nghttpx does
not show such difference, probably because buffer copy is not
bottleneck.  Using nghttp2_send_data_callback adds complexity, so it
is recommended to measure the performance to see whether this extra
complexity worth it.
2015-04-04 21:23:50 +09:00
..
_themes/sphinx_rtd_theme Update sphinx_rtd_theme 2015-04-01 23:11:07 +09:00
bash_completion Add bash_completion files for nghttp, nghttpd, nghttpx and h2load 2015-02-15 12:05:27 +09:00
sources Update doc 2015-04-01 23:10:01 +09:00
.gitignore doc: Update .gitignore 2015-04-01 01:19:08 +09:00
Makefile.am Add nghttp2_send_data_callback to send DATA payload without copying 2015-04-04 21:23:50 +09:00
README.rst Rebranding nghttp2 2013-07-13 00:43:06 +09:00
asio_http2.h.rst.in doc: Add language attribute in asio_http2.h.rst.in 2014-11-28 02:01:59 +09:00
asio_http2_client.h.rst.in Update documents using updated libnghttp2_asio API, including client API 2015-03-07 03:12:13 +09:00
asio_http2_server.h.rst.in Update documents using updated libnghttp2_asio API, including client API 2015-03-07 03:12:13 +09:00
building-android-binary.rst.in doc: Add building-android-binary document 2014-08-17 19:15:19 +09:00
conf.py.in Produce man pages using sphinx 2015-01-10 00:37:42 +09:00
contribute.rst.in Add contribution guidelines 2014-11-27 23:56:29 +09:00
h2load-howto.rst.in doc: Add h2load-howto.rst 2014-06-27 00:05:49 +09:00
h2load.1 Update man pages 2015-03-31 00:23:12 +09:00
h2load.1.rst Update man pages 2015-03-27 00:37:12 +09:00
h2load.h2r doc: Add output section to h2load man page 2015-02-01 16:36:58 +09:00
index.rst.in Out-of-tree build for sphinx documents 2014-02-13 23:44:54 +09:00
libnghttp2_asio.rst.in Update doc 2014-09-24 00:45:40 +09:00
make.bat Rebranding nghttp2 2013-07-13 00:43:06 +09:00
mkapiref.py doc: Split API reference into smaller fine grained files 2015-04-01 01:13:10 +09:00
nghttp.1 Update man pages 2015-03-31 00:23:12 +09:00
nghttp.1.rst Update man pages 2015-03-31 00:23:12 +09:00
nghttp.h2r Produce man pages using sphinx 2015-01-10 00:37:42 +09:00
nghttp2.h.rst.in Out-of-tree build for sphinx documents 2014-02-13 23:44:54 +09:00
nghttp2ver.h.rst.in Out-of-tree build for sphinx documents 2014-02-13 23:44:54 +09:00
nghttpd.1 Update man pages 2015-03-31 00:23:12 +09:00
nghttpd.1.rst Update man pages 2015-03-31 00:23:12 +09:00
nghttpd.h2r Produce man pages using sphinx 2015-01-10 00:37:42 +09:00
nghttpx-howto.rst.in doc: Use autoconf template nghttpx-howto.rst.in properly 2014-04-20 23:42:15 +09:00
nghttpx.1 Update man pages 2015-03-31 00:23:12 +09:00
nghttpx.1.rst Update man pages 2015-03-31 00:23:12 +09:00
nghttpx.h2r Mention OCSP stapling in doc 2015-03-31 23:31:24 +09:00
package_README.rst.in Out-of-tree build for sphinx documents 2014-02-13 23:44:54 +09:00
programmers-guide.rst doc: Split API reference into smaller fine grained files 2015-04-01 01:13:10 +09:00
python-apiref.rst.in doc: Fix python-apiref.rst is not generated in distribution 2014-06-29 23:57:18 +09:00
tutorial-client.rst.in Out-of-tree build for sphinx documents 2014-02-13 23:44:54 +09:00
tutorial-hpack.rst.in doc: Add HPACK API tutorial 2014-06-29 23:45:49 +09:00
tutorial-server.rst.in Out-of-tree build for sphinx documents 2014-02-13 23:44:54 +09:00

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-caled 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``.