Commit | Line | Data |
---|---|---|
43c59509 PP |
1 | // Render with Asciidoctor |
2 | ||
3 | = Babeltrace{nbsp}2 C API documentation guidelines | |
4 | Philippe Proulx <pproulx@efficios.com> | |
5 | 6 October 2019 | |
6 | ||
7 | This document explains how to write documentation for the | |
8 | Babeltrace{nbsp}2 C API. | |
9 | ||
10 | ||
11 | == General rules | |
12 | ||
13 | * Use four spaces to indent. | |
14 | ||
15 | * Try to stay behind the 72^th^ column mark if possible. | |
16 | ||
17 | * Use `+ +` wherever needed. | |
18 | ||
19 | * Refer to a function using the `func()` form and to an enumerator or | |
20 | type using the `#name` syntax. | |
21 | ||
22 | * When you refer to any keyword or definition, use the `\c` command if | |
23 | it's a single word, otherwise surround the words with `<code>` and | |
24 | `</code>`: | |
25 | + | |
26 | -- | |
27 | ---- | |
28 | @returns | |
29 | Event class on success, or \c NULL on error. | |
30 | ---- | |
31 | -- | |
32 | ||
33 | * Use the `\command` style in text and the `@command` style for other | |
34 | locations (for example, `@brief`, `@param`, `@sa`, `@file`). | |
35 | ||
36 | * Use a `@code{.unparsed}` block for a plain text block (shell input, | |
37 | for example): | |
38 | + | |
39 | ---- | |
40 | @code{.unparsed} | |
41 | $ BABELTRACE_DEV_MODE=1 BABELTRACE_MINIMAL_LOG_LEVEL=TRACE ./configure | |
42 | @endcode | |
43 | ---- | |
44 | ||
45 | * In the text, use `\bt_p{__param__}` to refer to the parameter named | |
46 | `__param__`. | |
47 | ||
48 | ||
49 | == Function documentation | |
50 | ||
51 | Full example: | |
52 | ||
53 | ---- | |
54 | /*! | |
55 | @brief | |
56 | Does something (third person singular, simple present) with some | |
57 | parameter \bt_p{param} unless some other parameter | |
58 | \bt_p{other_param} is some value. | |
59 | ||
60 | Full documentation goes here and adds any relevant information that's | |
61 | not in the brief description. | |
62 | ||
63 | @code | |
64 | /* If needed, put any C code in a code block. */ | |
65 | @endcode | |
66 | ||
67 | Crucifix scenester vegan organic neutra palo santo glossier occupy | |
68 | truffaut. Meh fixie taiyaki single-origin coffee wayfarers. Thundercats | |
69 | farm-to-table shoreditch vinyl. | |
70 | ||
71 | @remarks | |
72 | This is where you would put some remarks. Occupy flexitarian neutra, | |
73 | edison bulb bespoke sriracha post-ironic. Mlkshk plaid pop-up | |
74 | polaroid chillwave, ennui neutra. | |
75 | ||
76 | See this image: | |
77 | ||
78 | @image html mein-illustration.png "In elit et." | |
79 | ||
80 | @note | |
81 | @parblock | |
82 | This is a multiparagraph note. | |
83 | ||
84 | Tote bag sartorial distillery, try-hard succulents wayfarers DIY | |
85 | YOLO four loko jianbing farm-to-table unicorn vice. | |
86 | ||
87 | Mumblecore semiotics raw denim palo santo chartreuse helvetica | |
88 | shabby chic, distillery pabst poke swag copper mug blue bottle. | |
89 | @endpar | |
90 | ||
91 | @attention | |
92 | Use an attention command if this message is really important. | |
93 | ||
94 | @attention | |
95 | @parblock | |
96 | An attention block with more than one paragraph: | |
97 | ||
98 | @code | |
99 | some_code(23) | |
100 | @endcode | |
101 | ||
102 | Elit dolore pariatur ex anim officia cupidatat adipisicing mollit | |
103 | incididunt irure anim nostrud. | |
104 | @endparblock | |
105 | ||
106 | @param[in] param | |
107 | Description of this parameter. | |
108 | @param[in] other_param | |
109 | @parblock | |
110 | Description of this other parameter. Nulla consequat tempus libero, | |
111 | sed finibus velit. | |
112 | ||
113 | Offal actually vinyl taiyaki kickstarter etsy. | |
114 | @endparblock | |
115 | @param[out] out_param | |
116 | <strong>On success</strong>, \bt_p{*out_param} contains to something | |
117 | useful. | |
118 | ||
119 | @retval #SOME_STATUS_OK | |
120 | Success. | |
121 | @retval #SOME_STATUS_MEMORY_ERROR | |
122 | Out of memory. | |
123 | @retval #SOME_STATUS_ERROR | |
124 | @parblock | |
125 | Longer description for this specific status. | |
126 | ||
127 | Organic locavore sartorial 3 wolf moon brooklyn, VHS pug distillery | |
128 | schlitz tofu banjo chambray you probably haven't heard of them hot | |
129 | chicken copper mug. | |
130 | ||
131 | Neutra kale chips kombucha, salvia green juice live-edge swag | |
132 | biodiesel scenester austin yuccie dreamcatcher cronut small batch. | |
133 | @endparblock | |
134 | ||
135 | @bt_pre_not_null{param} | |
136 | @bt_pre_not_null{other_param} | |
137 | @bt_pre_hot{param} | |
138 | @pre | |
139 | \bt_p{param} is like this or like that. | |
140 | ||
141 | @bt_post_ref_cnt_same{other_param} | |
142 | @post | |
143 | \bt_p{other_param} is still in some state, and woke jean waistcoat. | |
144 | ||
145 | @sa bt_some_other_function() — | |
146 | Does something else with a parameter. | |
147 | @sa bt_another_function() — | |
148 | Cardigan celiac palo santo, tacos chicharrones pitchfork chambray | |
149 | photo booth subway tile 90's street. | |
150 | */ | |
151 | ---- | |
152 | ||
153 | Parts: | |
154 | ||
155 | . **Opening Doxygen comment**. | |
156 | + | |
157 | Use `/*!`. | |
158 | ||
159 | . **Brief description**. | |
160 | + | |
161 | Use third person singular in the simple present tense: you are | |
162 | documenting what the function does. Assume that the sentence implicitly | |
163 | starts with "`This function`". | |
164 | + | |
165 | Try to mention, briefly, all the parameters (with `\bt_p`) and what the | |
166 | function returns. | |
167 | + | |
168 | End the sentence with a period. | |
169 | ||
170 | ||
171 | . **Detailed description**. | |
172 | + | |
173 | Write complete sentences. | |
174 | + | |
175 | Refer to parameters (with `\bt_p`) as much as possible. | |
176 | + | |
177 | In general, keep paragraphs short: often, a single sentence is enough. | |
178 | + | |
179 | Write notes (`@note` command), remarks (`@remark` command), or | |
180 | attentions (`@attention` command) when appropriate. Most notes and | |
181 | remarks, however, can be simple paragraphs. Use `@parblock` end | |
182 | `@endparblock` to have more than one note/remark/warning paragraph. | |
183 | ||
184 | . **Parameter descriptions** (if any). | |
185 | + | |
186 | Use the `@param[in]`, `@param[out]`, and `@param[in,out]` commands | |
187 | depending on the parameter direction. | |
188 | + | |
189 | Document parameters in the declaration order. | |
190 | + | |
191 | Refer to other parameters (with `\bt_p`) when useful for the reader. | |
192 | + | |
193 | End each description with a period. | |
194 | + | |
195 | Use `@parblock` end `@endparblock` to have more than one paragraph for a | |
196 | given parameter description. | |
197 | + | |
198 | Make sure there's no blank line, except within a `@parblock` block, | |
199 | within the parameter description block so that Doxygen puts all the | |
200 | descriptions in the same section. For example, **do not** write this: | |
201 | + | |
202 | ---- | |
203 | @param[in] hexagon | |
204 | Ugh literally +1 aesthetic, fashion axe try-hard mixtape pork belly | |
205 | four loko. | |
206 | ||
207 | @param[in] selfies | |
208 | Brooklyn ethical migas, viral edison bulb meggings butcher | |
209 | flexitarian letterpress humblebrag kombucha pour-over etsy sriracha | |
210 | blog. | |
211 | ---- | |
212 | ||
213 | ||
214 | . **Return value** (if any). | |
215 | + | |
216 | -- | |
217 | * If the function returns a status code, use the `@retval` command | |
218 | multiple times to document each status: | |
219 | + | |
220 | ---- | |
221 | @retval #BT_VALUE_COPY_STATUS_OK | |
222 | Success. | |
223 | @retval #BT_VALUE_COPY_STATUS_MEMORY_ERROR | |
224 | Out of memory. | |
225 | ---- | |
226 | + | |
227 | End each description with a period. | |
228 | + | |
229 | Use `@parblock` end `@endparblock` to have more than one paragraph | |
230 | for a given return value description. | |
231 | + | |
232 | Make sure there's no blank line, except within a `@parblock` block, | |
233 | within the return value description block so that Doxygen puts all the | |
234 | descriptions in the same section. For example, **do not** write this: | |
235 | + | |
236 | ---- | |
237 | @retval #BT_VALUE_COPY_STATUS_OK | |
238 | Success. | |
239 | ||
240 | @retval #BT_VALUE_COPY_STATUS_MEMORY_ERROR | |
241 | Out of memory. | |
242 | ---- | |
243 | ||
244 | * If the function returns a simple value, use the `@returns` command | |
245 | to document it. | |
246 | + | |
247 | Refer to parameters (with `\bt_p`) when useful for the reader. | |
248 | + | |
249 | End the description with a period. | |
250 | -- | |
251 | ||
252 | . **Preconditions** (if any). | |
253 | + | |
254 | List all the function's preconditions with the `@pre` command or any | |
255 | alias which starts with `@bt_pre`. | |
256 | + | |
257 | Use the simple present tense. | |
258 | + | |
259 | Do not write the word "`must`" as a precondition is already a | |
260 | requirement. | |
261 | + | |
262 | End the description with a period. | |
263 | + | |
264 | Make sure there's no blank line within the precondition description | |
265 | block so that Doxygen puts all the descriptions in the same section. For | |
266 | example, **do not** write this: | |
267 | + | |
268 | ---- | |
269 | @bt_pre_hot{param} | |
270 | ||
271 | @pre | |
272 | \bt_p{param} is like this or like that. | |
273 | ---- | |
274 | ||
275 | . **Postconditions** (if any). | |
276 | + | |
277 | List all the function's _relevant_ postconditions with the `@post` | |
278 | command or any alias which starts with `@bt_post`. | |
279 | + | |
280 | Anything that the function's documentation body describes and which | |
281 | forms the nature of the function does not need to be written as an | |
282 | explicit postcondition. For example, if a function adds some object A | |
283 | to some object B, do not write the postcondition "B contains A". | |
284 | + | |
285 | Use the simple present tense. | |
286 | + | |
287 | End the description with a period. | |
288 | + | |
289 | Make sure there's no blank line within the postcondition description | |
290 | block so that Doxygen puts all the descriptions in the same section. For | |
291 | example, **do not** write this: | |
292 | + | |
293 | ---- | |
294 | @bt_post_ref_cnt_same{other_param} | |
295 | ||
296 | @post | |
297 | \bt_p{other_param} is still in some state, and woke jean waistcoat. | |
298 | ---- | |
299 | ||
300 | . **Items to see also** (if any). | |
301 | + | |
302 | Use the `@sa` command, multiple times if needed, to refer to related | |
303 | functions or types. | |
304 | + | |
305 | This is a way for you to inform the reader about other existing, related | |
306 | items. Keep in mind that the reader does not always know where to look | |
307 | for things. | |
308 | + | |
309 | In the referred item's brief description, do _not_ mention its | |
310 | parameters, if any. | |
311 | + | |
312 | End each brief description with a period. | |
313 | + | |
314 | Make sure there's no blank line within the "`see also`" description | |
315 | block so that Doxygen puts all the descriptions in the same section. For | |
316 | example, **do not** write this: | |
317 | + | |
318 | ---- | |
319 | @sa bt_some_other_function() — | |
320 | Does something else with a parameter. | |
321 | ||
322 | @sa bt_another_function() — | |
323 | Cardigan celiac palo santo, tacos chicharrones pitchfork chambray | |
324 | photo booth subway tile 90's street. | |
325 | ---- | |
326 | ||
327 | ||
328 | == Writing style | |
329 | ||
330 | The ultimate goal of the Babeltrace{nbsp}2 C API documentation is to | |
331 | make the layman write code using this API as fast and correct as | |
332 | possible without having to ask for help. For this purpose, the | |
333 | documentation must be as clear as possible, just like the function and | |
334 | type names try to be. | |
335 | ||
336 | Do not hesitate to repeat technical terms, even in the same sentence, if | |
337 | needed. For example, if you document a "`value object`", then always use | |
338 | the term "`value object`" in the documentation, not "`value`", nor | |
339 | "`object`", since they are ambiguous. | |
340 | ||
341 | You can use light emphasis to show the importance of a part of the text | |
342 | with the `\em` command (one word) or by surrounding the text to | |
343 | emphasize with `<em>` and `</em>`. Likewise, you can use strong emphasis | |
344 | when needed with the `\b` command (one word) or with `<strong>` and | |
345 | `</strong>`. In general, prefer light emphasis to strong emphasis, and | |
346 | use it economically. | |
347 | ||
348 | Links to other parts of the documentation are very important. Consider | |
349 | that the reader never knows that other functions exist other than the | |
350 | one she's reading. Use as many internal links as possible. Use the | |
351 | following forms of links: | |
352 | ||
353 | `__func__()`:: | |
354 | Automatic link to the function or macro named `__func__`. | |
355 | ||
356 | `#__name__`:: | |
357 | Automatic link to the type or enumerator named `__name__`. | |
358 | ||
359 | `\ref __ref__`:: | |
360 | Link to `__ref__` (page name, group name, function or macro name, | |
361 | type name, variable name, etc.) using its default text. | |
362 | ||
363 | `\ref __ref__ "__some text__"`:: | |
364 | Link to `__ref__` (page name, group name, function or macro name, | |
365 | type name, variable name, etc.) using the text `__some text__`. | |
366 | ||
367 | See Doxygen's http://www.doxygen.nl/manual/autolink.html[Automatic link | |
368 | generation] for other ways to create automatic links. | |
369 | ||
370 | Follow, as much as possible, the | |
371 | https://docs.microsoft.com/en-ca/style-guide/welcome/[Microsoft Style | |
372 | Guide] when you document the API. This includes: | |
373 | ||
374 | * Use an active voice. | |
375 | * Use a gender-neutral language. | |
376 | * Use the present tense (you almost never need the future tense). | |
377 | * Address your reader directly (use "`you`"). | |
378 | * Use contractions ("`it's`", "`you're`", "`don't`", and the rest). | |
379 | * Avoid anthropomorphism. | |
380 | * Ensure parallelism in lists, procedures, and sentences. | |
381 | * Terminate list items with a period. | |
382 | * Do not use Latin abbreviations. | |
383 | * Use "`and`" or "`or`" instead of a slash. | |
384 | * Avoid using negatives. | |
385 | * Avoid using "`should`": most of the time, you mean "`must`", and | |
386 | that's very clear for the reader. |