| 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. |