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