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