Project

General

Profile

Guidelines for API documentation » History » Version 14

neels, 12/11/2018 04:16 PM

1 1 neels
h1. Guidelines for API documentation
2
3 12 neels
Find the current API doc in HTML form here: http://ftp.osmocom.org/api/latest/
4
5 13 neels
We use doxygen for API documentation, for an overview see http://www.doxygen.nl/manual/docblocks.html. Please follow these guidelines:
6 1 neels
7 14 neels
h2. Marker style
8
9 1 neels
Use the @/*!@ (Qt-style) doxygen markers.
10 14 neels
<pre>
11
/*! Item summary.
12
 * Details follow. */
13
struct item {
14
    int member; /*!< Member summary. */
15
};
16
</pre>
17 1 neels
18 14 neels
h2. Summary
19
20
Since we are using the AUTOBRIEF feature, omit '\brief', and always end the first sentence with a full-stop "." to mark the end of the short description.
21
22
To have a dot in a summary, use an escaped space like
23 1 neels
<pre>/*! Brief description (e.g.\ using only a few words). Details follow. */</pre>
24
25
Never rely on line breaks as semantic separation or to end a sentence, always use proper punctuation. The API doc may be rendered with different line breaks than in the source file.
26 4 neels
27
h2. Locations
28
29
Header files usually contain merely function declarations bare of any API docs. The API doc comment should be in a @.c@ file at the definition of a function.
30
31
Structs and enums defined in a header file, though, also have their API doc comments in that @.h@ file.
32 10 neels
33
Comments for single-line items like enum values or struct members can be placed on the same line using @/*!< Description */@.
34 4 neels
35
h2. Grammar
36
37
Always use the imperative form, i.e. omit wording like "This function does", and avoid writing documentation that merely mirrors a function's name. For example:
38
39
<pre>
40
/*! Return a (static) buffer containing a hexdump of the msg.
41
 * \param[in] msg message buffer
42
 * \returns a pointer to a static char array
43
 */
44
const char *msgb_hexdump(const struct msgb *msg)
45
{
46
...
47
</pre>
48
49 1 neels
h2. Parameters
50 12 neels
51 4 neels
All parameters of a function should be documented. Input params are documented with @\param[in]@, where out-parameters (pointers to which returned data is written) are documented with @\param[out]@. Rarely, a param is both: @\param[in,out]@.
52
53
<pre>
54
/*! Apply nifty algorithm.
55
 * \param[in] x0  First factor.
56
 * \param[in] n   Amount of values to calculate.
57
 * \param[out] buf  Write calculated values to this buffer.
58
 *
59 1 neels
 * Optional longer function description. */
60 7 neels
</pre>
61 8 neels
62 4 neels
It is also possible to document parameters without a direction, using merely @\param param_name Description@, however, it is desirable to always indicate @[in]@, @[out]@ or @[inout]@.
63 1 neels
64
h2. File comments
65
66
If a file contains a descriptive comment, this comment should be right at the start of the file, as a doxygen @\file@ section.
67
The first sentence must be ended by a full stop "." to mark the end of the short description.
68
The copyright notice shall not be part of such API doc file comment.
69
70
<pre>
71
/*! \file foo.c
72
 * Short description. */
73
/*
74
 * (C) 2017 ... Copyright not in a doxygen comment
75
 * license information
76
 */
77
</pre>
78
79
or
80
81
<pre>
82
/*! \file foo.c
83
 * Short description.
84
 *
85
 * More information in multiple lines.
86
 */
87
/*
88
 * (C) 2017 ...
89
 */
90
</pre>
91 11 neels
92 9 neels
If a file needs no description, it is ok to omit the @\file@ tag entirely. Since we are using EXTRACT_ALL = YES, files lacking a @\file@ tag are still listed in the API docs.
93 1 neels
94
h2. Groups
95
96
Doxygen allows grouping elements: a group can include code elements and also entire files.
97
98
This works by enclosing the items to be grouped between an opening and a closing marker:
99
100
* A @\defgroup@ initially defines a group, this shall exist only once.
101
* More items can be added using an @\addtogroup@ marker.
102
* Both have to be closed by "@}".
103
104
For example:
105
106
<pre>
107
/*! \defgroup groupname Short description of the group.
108
 * @{
109
 */
110
111
struct type_that_belongs_to_group {
112
 ...
113
};
114
115
void func_that_belongs_to_group()
116
{
117
 ...
118
}
119
120
/*! @} */
121
</pre>
122
123
and 
124
125
<pre>
126
/*! \addtogroup groupname
127
 * @{
128
 */
129 3 neels
130 1 neels
...
131
132
/*! @} */
133
</pre>
134 5 neels
135 1 neels
If a *file* should be added to a group, add a (possibly second) short descriptionless @\file@ tag to the group start. To clearly mark that the purpose is to add to the group, do so within the same comment block:
136
137
<pre>
138 2 neels
/*! \file foo.c
139 1 neels
 * File's description. */
140
/*
141
 * (C) ...
142
 */
143
144
/*! \addtogroup groupname
145
 * @{
146
 * \file foo.c */
147
148
...
149
150
/*! @} */
151
</pre>
152
153
The point is that we like to have a file's short description near the start of the file, to also serve us well when we're reading only the .h file. But to be included in a group, the doxygen group start must precede the @\file@ tag. Also, the doxygen group should rather not enclose @#include@ directives, to clearly exclude those from the group. Hence, the best way is to keep the file's actual description at the top of the file, and add a second descriptionless @\file@ with the group opening.
154
155
A group may contain a short as well as a longer description. We often @\defgroup@ in a @.h@ file but keep the longer description in an @\addtogroup@ in a @.c@ file. Any @\file@ tags must follow *after* such description, or the description will be associated with the file instead of the group:
156
157
@.h@ file:
158
<pre>
159
/*! \defgroup groupname Short description of the group.
160
 * @{
161
 */
162
163
...
164
165
/*! @} */
166
</pre>
167
168
@.c file:
169
170
<pre>
171
/*! \addtogroup groupname
172
 * @{
173
 * Longer description of the group.
174
 * - contains a
175
 * - bullet list
176
 * 
177
 * As well as a 
178
 *
179
 *     Code example
180
 *     block
181 6 neels
 *
182 1 neels
 * All of which must not be below the directive adding this file to the group...
183
 *
184
 * \file foo.c */
185
186
[...]
187
188
/*! @} */
189
</pre>
190
191
Often, a file's description matches or is identical with a group's description. In that case, the file's description header comment can be omitted to avoid duplicating identical descriptions.
192
193
<pre>
194
/*
195
 * (C) 2017 ...
196
 */
197
198
/* \addtogroup group
199
 * @{
200
 * Description...
201
 *
202
 * \file foo.c */
203
204
...
205
206
/* @} */
207
</pre>
Add picture from clipboard (Maximum size: 48.8 MB)