| 1 | = Babeltrace C API documentation guidelines |
| 2 | |
| 3 | Please follow those guidelines when you add to or modify the existing |
| 4 | documentation of the Babeltrace C API. |
| 5 | |
| 6 | |
| 7 | == Syntax |
| 8 | |
| 9 | Syntax example to document a function (tabs are converted to spaces |
| 10 | in this example, but you really _must_ use tabs to indent): |
| 11 | |
| 12 | ---- |
| 13 | /** |
| 14 | @brief Sets the name of the CTF IR stream class \p stream_class |
| 15 | to \p name. |
| 16 | |
| 17 | \p name must be unique amongst the names of all the stream classes |
| 18 | of the trace class to which you eventually add \p stream_class. |
| 19 | |
| 20 | @remarks |
| 21 | This is where you would put some remarks. Lorem ipsum dolor sit amet, |
| 22 | consectetur adipiscing elit. Vestibulum sagittis tristique velit vitae |
| 23 | tincidunt. |
| 24 | |
| 25 | @warning |
| 26 | Use a warning command if this message is really important. |
| 27 | |
| 28 | @param[in] stream_class Stream class of which to set the name. |
| 29 | @param[in] name Name of the stream class (copied on success). If |
| 30 | the description is too long, continue on the |
| 31 | next line like this. |
| 32 | @returns 0 on success, or a negative value on error. |
| 33 | |
| 34 | @prenotnull{stream_class} |
| 35 | @prenotnull{name} |
| 36 | @prehot{stream_class} |
| 37 | @pre Some custom precondition. |
| 38 | @postrefcountsame{stream_class} |
| 39 | @post Some custom postcondition. |
| 40 | |
| 41 | @sa btstream_class_get_name(): Returns the name of a given stream class. |
| 42 | */ |
| 43 | ---- |
| 44 | |
| 45 | **Rules**: |
| 46 | |
| 47 | * Try to stay behind the 72th column mark if possible, and behind the |
| 48 | 80th column otherwise. |
| 49 | |
| 50 | * Start the block with |
| 51 | https://www.stack.nl/\~dimitri/doxygen/manual/commands.html#cmdbrief[`@brief`] |
| 52 | followed by a tab followed by the brief description. If the brief |
| 53 | description needs more than one line, start the following lines with a |
| 54 | tab character. |
| 55 | + |
| 56 | Try to always refer to all the function or macro parameters in the brief |
| 57 | description. The sentence _must_ begin with a verb, third-person |
| 58 | singular. The brief description _must_ contain a single sentence |
| 59 | which ends with a period. |
| 60 | + |
| 61 | Follow the brief description by zero or more paragraphs giving more |
| 62 | details about the object you are documenting. |
| 63 | + |
| 64 | You can also use the |
| 65 | https://www.stack.nl/\~dimitri/doxygen/manual/commands.html#cmdremark[`@remarks`] |
| 66 | and |
| 67 | https://www.stack.nl/\~dimitri/doxygen/manual/commands.html#cmdwarning[`@warning`] |
| 68 | commands as needed to add special paragraphs. |
| 69 | |
| 70 | * When you refer to parameters, use the |
| 71 | https://www.stack.nl/\~dimitri/doxygen/manual/commands.html#cmdp[`\p`] |
| 72 | command: |
| 73 | + |
| 74 | -- |
| 75 | ---- |
| 76 | @brief Transfers the ownership of a Babeltrace object from variable |
| 77 | \p _var_src to variable \p _var_dst. |
| 78 | ---- |
| 79 | -- |
| 80 | |
| 81 | * When you refer to any keyword or definition, use the |
| 82 | https://www.stack.nl/\~dimitri/doxygen/manual/commands.html#cmdc[`\c`] |
| 83 | command if it's a single word, otherwise surround the words with |
| 84 | `<code>` and `</code>`: |
| 85 | + |
| 86 | -- |
| 87 | ---- |
| 88 | @returns Event class on success, or \c NULL on error. |
| 89 | ---- |
| 90 | -- |
| 91 | |
| 92 | * Add a new line before the parameter descriptions. |
| 93 | |
| 94 | * The syntax for a parameter line is one of: |
| 95 | + |
| 96 | -- |
| 97 | ---- |
| 98 | @param[in] in_param Input parameter description. |
| 99 | @param[out] out_param Output parameter description. |
| 100 | @param[in,out] inout_param Input/output parameter description. |
| 101 | ---- |
| 102 | -- |
| 103 | + |
| 104 | That is: |
| 105 | + |
| 106 | -- |
| 107 | . https://www.stack.nl/\~dimitri/doxygen/manual/commands.html#cmdparam[`@param`] |
| 108 | . `[in]` (input parameter), `[out]` (output parameter), or `[in,out]` |
| 109 | (input/output parameter). |
| 110 | + |
| 111 | Output and input/output parameters are |
| 112 | always pointers where, for a parameter named `param`, a result is |
| 113 | stored _into_ `*param`. |
| 114 | |
| 115 | . A space. |
| 116 | . The name of the parameter. |
| 117 | . At least one tab. |
| 118 | . The description which ends with a period. |
| 119 | -- |
| 120 | + |
| 121 | Make sure all the beginnings of the parameter descriptions and of the |
| 122 | return value description are vertically aligned by using as many tabs as |
| 123 | required. |
| 124 | + |
| 125 | If more than one line is needed, align the beginning of the second line |
| 126 | with the beginning of the first one (see the return value description in |
| 127 | the example above). |
| 128 | |
| 129 | * The syntax for the return value line is: |
| 130 | + |
| 131 | -- |
| 132 | . https://www.stack.nl/\~dimitri/doxygen/manual/commands.html#cmdreturns[`@returns`] |
| 133 | (_not_ `@return`). |
| 134 | . At least one tab. |
| 135 | . The description which ends with a period. |
| 136 | -- |
| 137 | + |
| 138 | The return value description often takes the form: |
| 139 | + |
| 140 | -- |
| 141 | ---- |
| 142 | X on success, or Y on error. |
| 143 | ---- |
| 144 | -- |
| 145 | |
| 146 | * When needed, add an empty line after the return value line and add |
| 147 | preconditions and postconditions with the |
| 148 | https://www.stack.nl/\~dimitri/doxygen/manual/commands.html#cmdpre[`@pre`] |
| 149 | and |
| 150 | https://www.stack.nl/\~dimitri/doxygen/manual/commands.html#cmdpost[`@post`] |
| 151 | commands on the following lines. |
| 152 | + |
| 153 | Preconditions are a very clear way to indicate what the documented |
| 154 | function or macro expects from the user in relation to its parameters. |
| 155 | + |
| 156 | Postconditions are a very clear way to indicate what the user should |
| 157 | expect from the documented function or macro once it returns. |
| 158 | + |
| 159 | Use complete sentences, starting with a capital letter and ending with |
| 160 | a period, when writing conditions. Use the present tense. If there's a |
| 161 | conditional part, put it in bold at the beginning of the sentence. |
| 162 | + |
| 163 | If the condition is too long for a single line, continue on the |
| 164 | following line, after a tab. |
| 165 | + |
| 166 | Examples: |
| 167 | + |
| 168 | -- |
| 169 | ---- |
| 170 | @pre The size of \p array_obj is equal to the size of \p map_obj. |
| 171 | @post <strong>On success</strong>, the reference count of \p array_obj |
| 172 | is incremented. |
| 173 | @post The reference count of \p map_obj is not modified. |
| 174 | ---- |
| 175 | -- |
| 176 | + |
| 177 | IMPORTANT: You should use aliases when possible to avoid duplication. |
| 178 | See the list of available aliases in the `Doxyfile.in` file. |
| 179 | |
| 180 | * When relevant, add a new line after the return value line (or after |
| 181 | the precondition or postcondition lines, if any) and add |
| 182 | as many _see also_ links as needed on the following lines. |
| 183 | + |
| 184 | The syntax of those lines is: |
| 185 | + |
| 186 | -- |
| 187 | . https://www.stack.nl/\~dimitri/doxygen/manual/commands.html#cmdsa[`@sa`] |
| 188 | . A single space. |
| 189 | . The name of the function, macro, variable, group, file, or page name |
| 190 | to see also. |
| 191 | . `:` (colon). |
| 192 | . A single space. |
| 193 | . The capitalized brief description which ends with a period. The |
| 194 | sentence _must_ begin with a verb, third-person singular. |
| 195 | -- |
| 196 | + |
| 197 | This is a way for you to inform the reader about other existing, related |
| 198 | functions, macros, or any other documentation. Keep in mind that the |
| 199 | reader does not always know where to look for things. |
| 200 | + |
| 201 | If the description is too long for a single line, continue on the |
| 202 | following line, after a tab: |
| 203 | + |
| 204 | -- |
| 205 | ---- |
| 206 | @sa some_function() Lorem ipsum dolor sit amet, consectetur adipiscing |
| 207 | cras iaculis lectus quis dolor congue tempor. |
| 208 | ---- |
| 209 | -- |
| 210 | |
| 211 | * Always prefer the `@` commands to the `\` commands when you use them |
| 212 | outside of the text itself. |
| 213 | |
| 214 | |
| 215 | == Style |
| 216 | |
| 217 | The ultimate goal of the Babeltrace C API documentation is to make the |
| 218 | layman write code using this API as fast as possible without having to |
| 219 | ask for help. For this purpose, the documentation should always be as |
| 220 | clear as possible, just like the function and type names try to be. |
| 221 | |
| 222 | Do not hesitate to repeat technical terms, even in the same sentence, if |
| 223 | needed. For example, if you document a _value object_, then always use |
| 224 | the term _value object_ in the documentation, not _value_, nor _object_, |
| 225 | since they are ambiguous. |
| 226 | |
| 227 | You can use light emphasis to show the importance of a part of the text |
| 228 | with the |
| 229 | https://www.stack.nl/\~dimitri/doxygen/manual/commands.html#cmdem[`\em`] |
| 230 | command (one word) or by surrounding the text to emphasize with `<em>` |
| 231 | and `</em>`. Likewise, you can use strong emphasis when needed with the |
| 232 | https://www.stack.nl/\~dimitri/doxygen/manual/commands.html#cmdb[`\b`] |
| 233 | command (one word) or with `<strong>`/`</strong>`. In general, prefer |
| 234 | light emphasis to strong emphasis. |
| 235 | |
| 236 | Links to other parts of the documentation are very important. Consider |
| 237 | that the reader never knows that other functions exist other than the |
| 238 | current one. Use as many internal links as possible. Use the following |
| 239 | forms of links: |
| 240 | |
| 241 | * `func()`: automatic link to the function (or macro) `func()`. |
| 242 | * `file.h`: automatic link to the file named `file.h`. |
| 243 | * https://www.stack.nl/\~dimitri/doxygen/manual/commands.html#cmdref[`\ref |
| 244 | group`]: link to the |
| 245 | https://www.stack.nl/\~dimitri/doxygen/manual/grouping.html[group] |
| 246 | named `group` (prefer this over a link to a file). |
| 247 | * https://www.stack.nl/\~dimitri/doxygen/manual/commands.html#cmdref[`\ref |
| 248 | variable`]: link to the variable `variable`. |
| 249 | * https://www.stack.nl/\~dimitri/doxygen/manual/commands.html#cmdlink[`\link |
| 250 | reference some text\endlink`]: link to `reference` (file name, group |
| 251 | name, function or macro name, etc.) using the text `some text`. |
| 252 | + |
| 253 | Example: |
| 254 | + |
| 255 | -- |
| 256 | ---- |
| 257 | You can create a \link events CTF IR event\endlink using [...] |
| 258 | By calling \link func() said function\endlink, [...] |
| 259 | ---- |
| 260 | -- |
| 261 | + |
| 262 | -- |
| 263 | [NOTE] |
| 264 | .Doxygen limitation. |
| 265 | ==== |
| 266 | Do not put a space between the end of the text and the `\endlink` |
| 267 | command, because this space becomes part of the hyperlink's text. |
| 268 | |
| 269 | Do _not_ do: |
| 270 | |
| 271 | ---- |
| 272 | You can create a \link events CTF IR event \endlink using [...] |
| 273 | By calling \link func() said function \endlink, [...] |
| 274 | ---- |
| 275 | ==== |
| 276 | -- |
| 277 | |
| 278 | See Doxygen's |
| 279 | https://www.stack.nl/\~dimitri/doxygen/manual/autolink.html[Automatic |
| 280 | link generation] for other ways to create automatic links. |
| 281 | |
| 282 | Try to follow as much as possible the |
| 283 | https://en.wikipedia.org/wiki/Microsoft_Manual_of_Style[Microsoft Manual of Style] |
| 284 | (4th edition) when you document the API. This includes: |
| 285 | |
| 286 | * Use an active voice. |
| 287 | * Use a gender-neutral language. |
| 288 | * Use the present tense (you should never need the future tense). |
| 289 | * Address your reader directly (use _you_). |
| 290 | * Avoid anthropomorphism. |
| 291 | * Ensure parallelism in lists, procedures, and sentences. |
| 292 | * Terminate list items with a period. |
| 293 | * Do not use Latin abbreviations. |
| 294 | * Use _and_ or _or_ instead of a slash. |
| 295 | * Avoid using negatives. |
| 296 | * Avoid using _should_: most of the time, you mean _must_. |
| 297 | |
| 298 | |
| 299 | == Babeltrace terminology |
| 300 | |
| 301 | Here are the official names of the Babeltrace objects that you must use |
| 302 | as is in the API documentation: |
| 303 | |
| 304 | * Value objects: |
| 305 | ** The null value object (_the_, not _a_, since it's a singleton |
| 306 | variable) |
| 307 | ** Boolean value object |
| 308 | ** Integer value object |
| 309 | ** Floating point number value object |
| 310 | ** String value object |
| 311 | ** Array value object |
| 312 | ** Map value object |
| 313 | * CTF IR field path object |
| 314 | * CTF IR field types |
| 315 | ** CTF IR integer field type |
| 316 | ** CTF IR floating point number field type |
| 317 | ** CTF IR enumeration field type |
| 318 | ** CTF IR string field type |
| 319 | ** CTF IR array field type |
| 320 | ** CTF IR sequence field type |
| 321 | ** CTF IR structure field type |
| 322 | ** CTF IR variant field type |
| 323 | * CTF IR fields: |
| 324 | ** CTF IR integer field |
| 325 | ** CTF IR floating point number field |
| 326 | ** CTF IR enumeration field |
| 327 | ** CTF IR string field |
| 328 | ** CTF IR array field |
| 329 | ** CTF IR sequence field |
| 330 | ** CTF IR structure field |
| 331 | ** CTF IR variant field |
| 332 | * CTF IR clock class |
| 333 | * CTF IR event class |
| 334 | * CTF IR stream class |
| 335 | * CTF IR trace class |
| 336 | * CTF IR event |
| 337 | * CTF IR packet |
| 338 | * CTF IR stream |
| 339 | * CTF IR writer |
| 340 | * Component |
| 341 | * Source component |
| 342 | * Sink component |
| 343 | * Component class |
| 344 | * Source component class |
| 345 | * Sink component class |
| 346 | * Plugin |
| 347 | * Notification |
| 348 | * Iterator |
| 349 | |
| 350 | Note that once you mention _CTF IR_ in an object name, you can omit |
| 351 | it in the few following paragraphs. |