Project

General

Profile

Guidelines for API documentation » History » Version 13

neels, 12/11/2018 04:12 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
Use the @/*!@ (Qt-style) doxygen markers.
8
9
Since we are using the AUTOBRIEF feature, always end the first sentence with a full-stop "." to mark the end of the short description.
10 13 neels
This allows omitting the @\brief@ markers everywhere. To have a dot in a summary, use an escaped space like
11
<pre>/*! Brief description (e.g.\ using only a few words). Details follow. */</pre>
12 1 neels
13
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.
14
15 4 neels
h2. Locations
16
17
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.
18
19
Structs and enums defined in a header file, though, also have their API doc comments in that @.h@ file.
20
21 10 neels
Comments for single-line items like enum values or struct members can be placed on the same line using @/*!< Description */@.
22
23 4 neels
h2. Grammar
24
25
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:
26
27
<pre>
28
/*! Return a (static) buffer containing a hexdump of the msg.
29
 * \param[in] msg message buffer
30
 * \returns a pointer to a static char array
31
 */
32
const char *msgb_hexdump(const struct msgb *msg)
33
{
34
...
35
</pre>
36
37
h2. Parameters
38 1 neels
39 12 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]@.
40 4 neels
41
<pre>
42
/*! Apply nifty algorithm.
43
 * \param[in] x0  First factor.
44
 * \param[in] n   Amount of values to calculate.
45
 * \param[out] buf  Write calculated values to this buffer.
46
 *
47
 * Optional longer function description. */
48 1 neels
</pre>
49 7 neels
50 8 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]@.
51 4 neels
52 1 neels
h2. File comments
53
54
If a file contains a descriptive comment, this comment should be right at the start of the file, as a doxygen @\file@ section.
55
The first sentence must be ended by a full stop "." to mark the end of the short description.
56
The copyright notice shall not be part of such API doc file comment.
57
58
<pre>
59
/*! \file foo.c
60
 * Short description. */
61
/*
62
 * (C) 2017 ... Copyright not in a doxygen comment
63
 * license information
64
 */
65
</pre>
66
67
or
68
69
<pre>
70
/*! \file foo.c
71
 * Short description.
72
 *
73
 * More information in multiple lines.
74
 */
75
/*
76
 * (C) 2017 ...
77
 */
78
</pre>
79
80 11 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.
81 9 neels
82 1 neels
h2. Groups
83
84
Doxygen allows grouping elements: a group can include code elements and also entire files.
85
86
This works by enclosing the items to be grouped between an opening and a closing marker:
87
88
* A @\defgroup@ initially defines a group, this shall exist only once.
89
* More items can be added using an @\addtogroup@ marker.
90
* Both have to be closed by "@}".
91
92
For example:
93
94
<pre>
95
/*! \defgroup groupname Short description of the group.
96
 * @{
97
 */
98
99
struct type_that_belongs_to_group {
100
 ...
101
};
102
103
void func_that_belongs_to_group()
104
{
105
 ...
106
}
107
108
/*! @} */
109
</pre>
110
111
and 
112
113
<pre>
114
/*! \addtogroup groupname
115
 * @{
116
 */
117
118 3 neels
...
119 1 neels
120
/*! @} */
121
</pre>
122
123 5 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:
124 1 neels
125
<pre>
126
/*! \file foo.c
127 2 neels
 * File's description. */
128 1 neels
/*
129
 * (C) ...
130
 */
131
132
/*! \addtogroup groupname
133
 * @{
134
 * \file foo.c */
135
136
...
137
138
/*! @} */
139
</pre>
140
141
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.
142
143
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:
144
145
@.h@ file:
146
<pre>
147
/*! \defgroup groupname Short description of the group.
148
 * @{
149
 */
150
151
...
152
153
/*! @} */
154
</pre>
155
156
@.c file:
157
158
<pre>
159
/*! \addtogroup groupname
160
 * @{
161
 * Longer description of the group.
162
 * - contains a
163
 * - bullet list
164
 * 
165
 * As well as a 
166
 *
167
 *     Code example
168
 *     block
169
 *
170 6 neels
 * All of which must not be below the directive adding this file to the group...
171 1 neels
 *
172
 * \file foo.c */
173
174
[...]
175
176
/*! @} */
177
</pre>
178
179
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.
180
181
<pre>
182
/*
183
 * (C) 2017 ...
184
 */
185
186
/* \addtogroup group
187
 * @{
188
 * Description...
189
 *
190
 * \file foo.c */
191
192
...
193
194
/* @} */
195
</pre>
Add picture from clipboard (Maximum size: 48.8 MB)