1 // Render with Asciidoctor
3 = Babeltrace{nbsp}2 C API documentation guidelines
4 Philippe Proulx <pproulx@efficios.com>
7 This document explains how to write documentation for the
8 Babeltrace{nbsp}2 C API.
13 * Use four spaces to indent.
15 * Try to stay behind the 72^th^ column mark if possible.
17 * Use `+ +` wherever needed.
19 * Refer to a function using the `func()` form and to an enumerator or
20 type using the `#name` syntax.
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
29 Event class on success, or \c NULL on error.
33 * Use the `\command` style in text and the `@command` style for other
34 locations (for example, `@brief`, `@param`, `@sa`, `@file`).
36 * Use a `@code{.unparsed}` block for a plain text block (shell input,
41 $ BABELTRACE_DEV_MODE=1 BABELTRACE_MINIMAL_LOG_LEVEL=TRACE ./configure
45 * In the text, use `\bt_p{__param__}` to refer to the parameter named
49 == Function documentation
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.
60 Full documentation goes here and adds any relevant information that's
61 not in the brief description.
64 /* If needed, put any C code in a code block. */
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.
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.
78 @image html mein-illustration.png "In elit et."
82 This is a multiparagraph note.
84 Tote bag sartorial distillery, try-hard succulents wayfarers DIY
85 YOLO four loko jianbing farm-to-table unicorn vice.
87 Mumblecore semiotics raw denim palo santo chartreuse helvetica
88 shabby chic, distillery pabst poke swag copper mug blue bottle.
92 Use an attention command if this message is really important.
96 An attention block with more than one paragraph:
102 Elit dolore pariatur ex anim officia cupidatat adipisicing mollit
103 incididunt irure anim nostrud.
107 Description of this parameter.
108 @param[in] other_param
110 Description of this other parameter. Nulla consequat tempus libero,
113 Offal actually vinyl taiyaki kickstarter etsy.
115 @param[out] out_param
116 <strong>On success</strong>, \bt_p{*out_param} contains to something
119 @retval #SOME_STATUS_OK
121 @retval #SOME_STATUS_MEMORY_ERROR
123 @retval #SOME_STATUS_ERROR
125 Longer description for this specific status.
127 Organic locavore sartorial 3 wolf moon brooklyn, VHS pug distillery
128 schlitz tofu banjo chambray you probably haven't heard of them hot
131 Neutra kale chips kombucha, salvia green juice live-edge swag
132 biodiesel scenester austin yuccie dreamcatcher cronut small batch.
135 @bt_pre_not_null{param}
136 @bt_pre_not_null{other_param}
139 \bt_p{param} is like this or like that.
141 @bt_post_ref_cnt_same{other_param}
143 \bt_p{other_param} is still in some state, and woke jean waistcoat.
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.
155 . **Opening Doxygen comment**.
159 . **Brief description**.
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`".
165 Try to mention, briefly, all the parameters (with `\bt_p`) and what the
168 End the sentence with a period.
171 . **Detailed description**.
173 Write complete sentences.
175 Refer to parameters (with `\bt_p`) as much as possible.
177 In general, keep paragraphs short: often, a single sentence is enough.
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.
184 . **Parameter descriptions** (if any).
186 Use the `@param[in]`, `@param[out]`, and `@param[in,out]` commands
187 depending on the parameter direction.
189 Document parameters in the declaration order.
191 Refer to other parameters (with `\bt_p`) when useful for the reader.
193 End each description with a period.
195 Use `@parblock` end `@endparblock` to have more than one paragraph for a
196 given parameter description.
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:
204 Ugh literally +1 aesthetic, fashion axe try-hard mixtape pork belly
208 Brooklyn ethical migas, viral edison bulb meggings butcher
209 flexitarian letterpress humblebrag kombucha pour-over etsy sriracha
214 . **Return value** (if any).
217 * If the function returns a status code, use the `@retval` command
218 multiple times to document each status:
221 @retval #BT_VALUE_COPY_STATUS_OK
223 @retval #BT_VALUE_COPY_STATUS_MEMORY_ERROR
227 End each description with a period.
229 Use `@parblock` end `@endparblock` to have more than one paragraph
230 for a given return value description.
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:
237 @retval #BT_VALUE_COPY_STATUS_OK
240 @retval #BT_VALUE_COPY_STATUS_MEMORY_ERROR
244 * If the function returns a simple value, use the `@returns` command
247 Refer to parameters (with `\bt_p`) when useful for the reader.
249 End the description with a period.
252 . **Preconditions** (if any).
254 List all the function's preconditions with the `@pre` command or any
255 alias which starts with `@bt_pre`.
257 Use the simple present tense.
259 Do not write the word "`must`" as a precondition is already a
262 End the description with a period.
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:
272 \bt_p{param} is like this or like that.
275 . **Postconditions** (if any).
277 List all the function's _relevant_ postconditions with the `@post`
278 command or any alias which starts with `@bt_post`.
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".
285 Use the simple present tense.
287 End the description with a period.
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:
294 @bt_post_ref_cnt_same{other_param}
297 \bt_p{other_param} is still in some state, and woke jean waistcoat.
300 . **Items to see also** (if any).
302 Use the `@sa` command, multiple times if needed, to refer to related
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
309 In the referred item's brief description, do _not_ mention its
312 End each brief description with a period.
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:
319 @sa bt_some_other_function() —
320 Does something else with a parameter.
322 @sa bt_another_function() —
323 Cardigan celiac palo santo, tacos chicharrones pitchfork chambray
324 photo booth subway tile 90's street.
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.
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.
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
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:
354 Automatic link to the function or macro named `__func__`.
357 Automatic link to the type or enumerator named `__name__`.
360 Link to `__ref__` (page name, group name, function or macro name,
361 type name, variable name, etc.) using its default text.
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__`.
367 See Doxygen's http://www.doxygen.nl/manual/autolink.html[Automatic link
368 generation] for other ways to create automatic links.
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:
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.