doc/README.rst

   1 nghttp2 Documentation
   2 =====================
   3
   4 The documentation of nghttp2 is generated using Sphinx.  This
   5 directory contains the source files to be processed by Sphinx.  The
   6 source file for API reference is generated using a script called
   7 ``mkapiref.py`` from the nghttp2 C source code.
   8
   9 Generating API reference
  10 ------------------------
  11
  12 As described earlier, we use ``mkapiref.py`` to generate rst formatted
  13 text of API reference from C source code.  The ``mkapiref.py`` is not
  14 so flexible and it requires that C source code is formatted in rather
  15 strict rules.
  16
  17 To generate API reference, just run ``make html``. It runs
  18 ``mkapiref.py`` and then run Sphinx to build the entire document.
  19
  20 The ``mkapiref.py`` reads C source code and searches the comment block
  21 starts with ``/**``. In other words, it only processes the comment
  22 block starting ``/**``. The comment block must end with ``*/``. The
  23 ``mkapiref.py`` requires that which type of the object this comment
  24 block refers to.  To specify the type of the object, the next line
  25 must contain the so-caled action keyword.  Currently, the following
  26 action keywords are supported: ``@function``, ``@functypedef``,
  27 ``@enum``, ``@struct`` and ``@union``. The following sections
  28 describes each action keyword.
  29
  30 @function
  31 #########
  32
  33 ``@function`` is used to refer to the function.  The comment block is
  34 used for the document for the function.  After the script sees the end
  35 of the comment block, it consumes the lines as the function
  36 declaration until the line which ends with ``;`` is encountered.
  37
  38 In Sphinx doc, usually the function argument is formatted like
  39 ``*this*``.  But in C, ``*`` is used for dereferencing a pointer and
  40 we must escape ``*`` with a back slash. To avoid this, we format the
  41 argument like ``|this|``. The ``mkapiref.py`` translates it with
  42 ``*this*``, as escaping ``*`` inside ``|`` and ``|`` as necessary.
  43 Note that this shadows the substitution feature of Sphinx.
  44
  45 The example follows::
  46
  47     /**
  48      * @function
  49      *
  50      * Submits PING frame to the |session|.
  51      */
  52     int nghttp2_submit_ping(nghttp2_session *session);
  53
  54
  55 @functypedef
  56 ############
  57
  58 ``@functypedef`` is used to refer to the typedef of the function
  59 pointer. The formatting rule is pretty much the same with
  60 ``@function``, but this outputs ``type`` domain, rather than
  61 ``function`` domain.
  62
  63 The example follows::
  64
  65     /**
  66      * @functypedef
  67      *
  68      * Callback function invoked when |session| wants to send data to
  69      * remote peer.
  70      */
  71     typedef ssize_t (*nghttp2_send_callback)
  72     (nghttp2_session *session,
  73      const uint8_t *data, size_t length, int flags, void *user_data);
  74
  75 @enum
  76 #####
  77
  78 ``@enum`` is used to refer to the enum.  Currently, only enum typedefs
  79 are supported.  The comment block is used for the document for the
  80 enum type itself. To document each values, put comment block starting
  81 with the line ``/**`` and ending with the ``*/`` just before the enum
  82 value.  When the line starts with ``}`` is encountered, the
  83 ``mkapiref.py`` extracts strings next to ``}`` as the name of enum.
  84
  85 At the time of this writing, Sphinx does not support enum type. So we
  86 use ``type`` domain for enum it self and ``macro`` domain for each
  87 value. To refer to the enum value, use ``:enum:`` pseudo role. The
  88 ``mkapiref.py`` replaces it with ``:macro:``. By doing this, when
  89 Sphinx will support enum officially, we can replace ``:enum:`` with
  90 the official role easily.
  91
  92 The example follows::
  93
  94     /**
  95      * @enum
  96      * Error codes used in the nghttp2 library.
  97      */
  98     typedef enum {
  99       /**
 100        * Invalid argument passed.
 101        */
 102       NGHTTP2_ERR_INVALID_ARGUMENT = -501,
 103       /**
 104        * Zlib error.
 105        */
 106       NGHTTP2_ERR_ZLIB = -502,
 107     } nghttp2_error;
 108
 109 @struct
 110 #######
 111
 112 ``@struct`` is used to refer to the struct. Currently, only struct
 113 typedefs are supported. The comment block is used for the document for
 114 the struct type itself.To document each member, put comment block
 115 starting with the line ``/**`` and ending with the ``*/`` just before
 116 the member.  When the line starts with ``}`` is encountered, the
 117 ``mkapiref.py`` extracts strings next to ``}`` as the name of struct.
 118 The block-less typedef is also supported. In this case, typedef
 119 declaration must be all in one line and the ``mkapiref.py`` uses last
 120 word as the name of struct.
 121
 122 Some examples follow::
 123
 124     /**
 125      * @struct
 126      * The control frame header.
 127      */
 128     typedef struct {
 129       /**
 130        * SPDY protocol version.
 131        */
 132       uint16_t version;
 133       /**
 134        * The type of this control frame.
 135        */
 136       uint16_t type;
 137       /**
 138        * The control frame flags.
 139        */
 140       uint8_t flags;
 141       /**
 142        * The length field of this control frame.
 143        */
 144       int32_t length;
 145     } nghttp2_ctrl_hd;
 146
 147     /**
 148      * @struct
 149      *
 150      * The primary structure to hold the resources needed for a SPDY
 151      * session. The details of this structure is hidden from the public
 152      * API.
 153      */
 154     typedef struct nghttp2_session nghttp2_session;
 155
 156 @union
 157 ######
 158
 159 ``@union`` is used to refer to the union. Currently, ``@union`` is an
 160 alias of ``@struct``.