README.rst
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