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