mirror of
https://github.com/moparisthebest/spdylay
synced 2024-12-22 15:48:53 -05:00
161 lines
5.0 KiB
ReStructuredText
161 lines
5.0 KiB
ReStructuredText
Spdylay Documentation
|
|
=====================
|
|
|
|
The documentation of Spdylay 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 Spdylay 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 spdylay_submit_ping(spdylay_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 (*spdylay_send_callback)
|
|
(spdylay_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 Spdylay library.
|
|
*/
|
|
typedef enum {
|
|
/**
|
|
* Invalid argument passed.
|
|
*/
|
|
SPDYLAY_ERR_INVALID_ARGUMENT = -501,
|
|
/**
|
|
* Zlib error.
|
|
*/
|
|
SPDYLAY_ERR_ZLIB = -502,
|
|
} spdylay_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;
|
|
} spdylay_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 spdylay_session spdylay_session;
|
|
|
|
@union
|
|
######
|
|
|
|
``@union`` is used to refer to the union. Currently, ``@union`` is an
|
|
alias of ``@struct``.
|