1nghttp2 Documentation 2===================== 3 4The documentation of nghttp2 is generated using Sphinx. This 5directory contains the source files to be processed by Sphinx. The 6source file for API reference is generated using a script called 7``mkapiref.py`` from the nghttp2 C source code. 8 9Generating API reference 10------------------------ 11 12As described earlier, we use ``mkapiref.py`` to generate rst formatted 13text of API reference from C source code. The ``mkapiref.py`` is not 14so flexible and it requires that C source code is formatted in rather 15strict rules. 16 17To generate API reference, just run ``make html``. It runs 18``mkapiref.py`` and then run Sphinx to build the entire document. 19 20The ``mkapiref.py`` reads C source code and searches the comment block 21starts with ``/**``. In other words, it only processes the comment 22block starting ``/**``. The comment block must end with ``*/``. The 23``mkapiref.py`` requires that which type of the object this comment 24block refers to. To specify the type of the object, the next line 25must contain the so-called action keyword. Currently, the following 26action keywords are supported: ``@function``, ``@functypedef``, 27``@enum``, ``@struct`` and ``@union``. The following sections 28describes each action keyword. 29 30@function 31######### 32 33``@function`` is used to refer to the function. The comment block is 34used for the document for the function. After the script sees the end 35of the comment block, it consumes the lines as the function 36declaration until the line which ends with ``;`` is encountered. 37 38In Sphinx doc, usually the function argument is formatted like 39``*this*``. But in C, ``*`` is used for dereferencing a pointer and 40we must escape ``*`` with a back slash. To avoid this, we format the 41argument like ``|this|``. The ``mkapiref.py`` translates it with 42``*this*``, as escaping ``*`` inside ``|`` and ``|`` as necessary. 43Note that this shadows the substitution feature of Sphinx. 44 45The 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 59pointer. The formatting rule is pretty much the same with 60``@function``, but this outputs ``type`` domain, rather than 61``function`` domain. 62 63The 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 79are supported. The comment block is used for the document for the 80enum type itself. To document each values, put comment block starting 81with the line ``/**`` and ending with the ``*/`` just before the enum 82value. When the line starts with ``}`` is encountered, the 83``mkapiref.py`` extracts strings next to ``}`` as the name of enum. 84 85At the time of this writing, Sphinx does not support enum type. So we 86use ``type`` domain for enum it self and ``macro`` domain for each 87value. To refer to the enum value, use ``:enum:`` pseudo role. The 88``mkapiref.py`` replaces it with ``:macro:``. By doing this, when 89Sphinx will support enum officially, we can replace ``:enum:`` with 90the official role easily. 91 92The 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 113typedefs are supported. The comment block is used for the document for 114the struct type itself.To document each member, put comment block 115starting with the line ``/**`` and ending with the ``*/`` just before 116the member. When the line starts with ``}`` is encountered, the 117``mkapiref.py`` extracts strings next to ``}`` as the name of struct. 118The block-less typedef is also supported. In this case, typedef 119declaration must be all in one line and the ``mkapiref.py`` uses last 120word as the name of struct. 121 122Some 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 160alias of ``@struct``. 161