1 // Render with Asciidoctor
3 = LTTng-tools C API documentation guidelines
4 Philippe Proulx <pproulx@efficios.com>
8 This document explains how to write documentation for the LTTng-tools
13 * Use four spaces to indent Doxygen text and two spaces to indent HTML.
15 * Try to stay behind the 72^th^ column mark when possible.
17 * Use https://en.wikipedia.org/wiki/Non-breaking_space[`+ +`]
20 * Refer to a function with the `func()` form and to an
21 enumerator/structure/variable or type with the `#name` syntax.
23 You don't need any `struct`/`enum` prefix with Doxygen.
25 * When you refer to any keyword or definition, use the `+\c+` command if
26 it's a single word, otherwise surround the words with `<code>` and
32 Event rule on success, or \c NULL on error.
36 * Use the `$$\$$__command__` style in text (paragraphs, list items,
37 definition terms, and the rest) and the `@__command__` style for
38 other locations (for example, `@brief`, `@param`, `@sa`, `@file`).
40 * Use a `@code{.unparsed}` block for a plain text block (shell input,
45 $ lttng enable-event --all --kernel --syscall
49 * In the text, use custom aliases when applicable.
51 See `Doxyfile.in` for the list of available aliases.
53 == Function documentation
60 Does something (third person singular, simple present) with some
61 parameter \lt_p{param} unless some other parameter
62 \lt_p{other_param} has some value.
64 Full documentation goes here and adds any relevant information that's
65 not in the brief description.
68 /* If needed, put any C code in a code block. */
71 Crucifix scenester vegan organic neutra palo santo glossier occupy
72 truffaut. Meh fixie taiyaki single-origin coffee wayfarers. Thundercats
73 farm-to-table shoreditch vinyl.
76 This is where you would put some remarks. Occupy flexitarian neutra,
77 edison bulb bespoke sriracha post-ironic. Mlkshk plaid pop-up
78 polaroid chillwave, ennui neutra.
82 @image html mein-illustration.png "Caption goes here."
86 This is a multiparagraph note.
88 Tote bag sartorial distillery, try-hard succulents wayfarers DIY
89 YOLO four loko jianbing farm-to-table unicorn vice.
91 Mumblecore semiotics raw denim palo santo chartreuse helvetica
92 shabby chic, distillery pabst poke swag copper mug blue bottle.
96 Use an attention command if this message is really important.
100 An attention block with more than one paragraph:
106 Elit dolore pariatur ex anim officia cupidatat adipisicing mollit
107 incididunt irure anim nostrud.
111 Description of this parameter.
112 @param[in] other_param
114 Description of this other parameter. Nulla consequat tempus libero,
117 Offal actually vinyl taiyaki kickstarter etsy.
119 @param[out] out_param
120 <strong>On success</strong>, \lt_p{*out_param} contains to something
123 @retval #LTTNG_SOME_STATUS_OK
125 @retval #LTTNG_SOME_STATUS_MEMORY_ERROR
127 @retval #LTTNG_SOME_STATUS_ERROR
129 Longer description for this specific status.
131 Organic locavore sartorial 3 wolf moon brooklyn, VHS pug distillery
132 schlitz tofu banjo chambray you probably haven't heard of them hot
135 Neutra kale chips kombucha, salvia green juice live-edge swag
136 biodiesel scenester austin yuccie dreamcatcher cronut small batch.
139 @lt_pre_not_null{param}
140 @lt_pre_not_null{other_param}
142 \lt_p{param} is like this or like that.
145 \lt_p{other_param} is still in some state, and woke jean waistcoat.
147 @sa lttng_some_other_function() --
148 Does something else with some parameter.
149 @sa lttng_another_function() --
150 Cardigan celiac palo santo, tacos chicharrones pitchfork chambray
151 photo booth subway tile 90's street.
157 . **Opening Doxygen comment**.
161 . **Brief description**.
163 Use third person singular in the simple present tense: you're
164 documenting what the function does. Assume that the sentence implicitly
165 starts with "`This function`".
167 Try to mention, briefly, all the parameters (with `\lt_p`) and what the
170 End the sentence with a period.
172 . **Detailed description**.
174 Write complete sentences.
176 Refer to parameters (with `\lt_p`) as much as possible.
178 In general, keep paragraphs short: often, a single sentence is enough.
180 Refer to the documented function with "`this function`".
182 Write notes (`@note` command), remarks (`@remark` command), or
183 attentions (`@attention` command) when needed. Most notes and remarks,
184 however, can be simple paragraphs. Use `@parblock` end `@endparblock` to
185 have more than one note/remark/warning paragraph.
187 . **Parameter descriptions** (if any).
189 Use the `@param[in]`, `@param[out]`, and `@param[in,out]` commands
190 depending on the parameter direction.
192 Document parameters in the declaration order.
194 Refer to other parameters (with `\lt_p`) when useful for the reader.
196 End each description with a period.
198 Use `@parblock` end `@endparblock` to have more than one paragraph for a
199 given parameter description.
201 Make sure there's no blank line, except within a `@parblock` block,
202 within the parameter description block so that Doxygen puts all the
203 descriptions in the same section. For example, _don't_ write this:
207 Ugh literally +1 aesthetic, fashion axe try-hard mixtape pork belly
211 Brooklyn ethical migas, viral edison bulb meggings butcher
212 flexitarian letterpress humblebrag kombucha pour-over etsy sriracha
216 . **Return value** (if any).
218 If the function returns a status code::
219 Use the `@retval` command multiple times to document each relevant
223 @retval #LTTNG_SOME_STATUS_OK
225 @retval #LTTNG_SOME_STATUS_SOME_ERROR
229 End each description with a period.
231 Use `@parblock` and `@endparblock` to have more than one paragraph for a
232 given return value description.
234 Make sure there's no blank line, except within a `@parblock` block,
235 within the return value description block so that Doxygen puts all the
236 descriptions in the same section. For example, _don't_ write this:
239 @retval #LTTNG_SOME_STATUS_OK
242 @retval #LTTNG_SOME_STATUS_SOME_ERROR
246 If the function returns a simple value::
247 Use the `@returns` command to document it.
249 Refer to parameters (with `\lt_p`) when useful for the reader.
251 End the description with a period.
253 . **Preconditions** (if any).
255 List all the function's preconditions with the `@pre` command or any
256 alias which starts with `@lt_pre` (see `Doxyfile.in`).
258 Use the simple present tense.
260 Do not write the word "`must`" as a precondition is already a
263 End the description with a period.
265 Make sure there's no blank line within the precondition description
266 block so that Doxygen puts all the descriptions in the same section. For
267 example, _don't_ write this:
270 @lt_pre_not_null{param}
273 \lt_p{param} is like this or like that.
276 . **Postconditions** (if any).
278 List all the function's _relevant_ postconditions with the `@post`
279 command or any alias which starts with `@lt_post` (see `Doxyfile.in`).
281 Anything that the body of the function documentation describes and which
282 forms the nature of the function doesn't need to be written as an
283 explicit postcondition. For example, if a function adds some
284 object{nbsp}A to some object{nbsp}B, don't write the postcondition
285 "`B{nbsp}contains{nbsp}A`".
287 Use the simple present tense.
289 End the description with a period.
291 Make sure there's no blank line within the postcondition description
292 block so that Doxygen puts all the descriptions in the same section. For
293 example, _don't_ write this:
297 The returned pointer is blue.
300 \lt_p{other_param} is still in some state, and woke jean waistcoat.
303 . **Items to see also** (if any).
305 Use the `@sa` command, multiple times if needed, to refer to related
308 This is a way for you to inform the reader about other existing, related
309 items. Keep in mind that the reader doesn't always know where to look
312 In the brief description of the referred item, _don't_ mention its
315 End each brief description with a period.
317 Make sure there's no blank line within the item description block so
318 that Doxygen puts all the descriptions in the same section. For example,
322 @sa lttng_some_other_function() --
323 Does something else with a parameter.
325 @sa lttng_another_function() --
326 Cardigan celiac palo santo, tacos chicharrones pitchfork chambray
327 photo booth subway tile 90's street.
333 The ultimate goal of the LTTng-tools C{nbsp}API documentation is to make
334 the layman write code using this API as fast and correct as possible
335 without having to ask for help. For this purpose, the documentation must
336 be as clear as possible, just like the function and type names try to
339 Don't hesitate to repeat technical terms, even in the same sentence, if
340 needed. For example, if you document an "`event rule`", then always use
341 the term "`event rule`" in the documentation, not "`event`", nor
342 "`rule`", since they are ambiguous.
344 You can use light emphasis to show the importance of a part of the text
345 with the `\em` command (one word) or by surrounding the text to
346 emphasize with `<em>` and `</em>`. Likewise, you can use strong emphasis
347 when needed with the `\b` command (one word) or with `<strong>` and
348 `</strong>`. In general, prefer light emphasis to strong emphasis, and
351 Links to other parts of the documentation are very important. Consider
352 that the reader never knows that other functions exist other than the
353 one she's reading. Use as many internal links as possible. Use the
354 following forms of links:
357 Automatic link to the function or macro named `__func__`.
360 Automatic link to the type or enumerator named `__name__`.
363 Link to `__ref__` (page name, group name, function or macro name,
364 type name, variable name, etc.) using its default text.
366 `\ref __ref__ "__some text__"`::
367 Link to `__ref__` (page name, group name, function or macro name,
368 type name, variable name, etc.) using the text `__some text__`.
370 See Doxygen's "`http://www.doxygen.nl/manual/autolink.html[Automatic
371 link generation]`" page for other ways to create automatic links.
373 Follow, as much as possible, the
374 https://docs.microsoft.com/en-ca/style-guide/welcome/[Microsoft Style
375 Guide] when you document the API. This includes:
377 * Use an active voice.
378 * Use a gender-neutral language.
379 * Use the present tense (you almost never need the future tense).
380 * Address your reader directly (use "`you`").
381 * Use contractions ("`it's`", "`you're`", "`don't`", and the rest).
382 * Avoid anthropomorphism.
383 * Ensure parallelism in lists, procedures, and sentences.
384 * Terminate list items with a period, except when the list only contains
386 * Do not use Latin abbreviations.
387 * Use "`and`" or "`or`" instead of a slash.
388 * Avoid using negatives.
389 * Avoid using "`should`": most of the time, you mean "`must`", and
390 that's very clear for the reader.