doc/api/README.adoc

   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.