Project

General

Profile

Guidelines for API documentation » History » Version 8

neels, 06/20/2017 02:19 AM

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