doc/api/dox: update pages
[babeltrace.git] / doc / api / README.adoc
CommitLineData
3758cf40
PP
1= Babeltrace C API documentation guidelines
2
3Please follow those guidelines when you add to or modify the existing
4documentation of the Babeltrace C API.
5
6
7== Syntax
8
9Syntax example to document a function (tabs are converted to spaces
10in 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
18of the trace class to which you eventually add \p stream_class.
19
20@remarks
21This is where you would put some remarks. Lorem ipsum dolor sit amet,
22consectetur adipiscing elit. Vestibulum sagittis tristique velit vitae
23tincidunt.
24
25@warning
26Use 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 space followed by a tab followed by the brief
54 description. If the brief description needs more than one line, start
55 the following lines with a tab character.
56+
57Try to always refer to all the function or macro parameters in the brief
58description. The sentence _must_ begin with a verb, third-person
59singular. The brief description _must_ contain a single sentence
60which ends with a period.
61+
62Follow the brief description by zero or more paragraphs giving more
63details about the object you are documenting.
64+
65You can also use the
66https://www.stack.nl/\~dimitri/doxygen/manual/commands.html#cmdremark[`@remarks`]
67and
68https://www.stack.nl/\~dimitri/doxygen/manual/commands.html#cmdwarning[`@warning`]
69commands 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+
105That 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+
112Output and input/output parameters are
113always pointers where, for a parameter named `param`, a result is
114stored _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+
122Make sure all the beginnings of the parameter descriptions and of the
123return value description are vertically aligned by using as many tabs as
124required.
125+
126If more than one line is needed, align the beginning of the second line
127with the beginning of the first one (see the return value description in
128the 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+
139The return value description often takes the form:
140+
141--
142----
143X 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+
154Preconditions are a very clear way to indicate what the documented
155function or macro expects from the user in relation to its parameters.
156+
157Postconditions are a very clear way to indicate what the user should
158expect from the documented function or macro once it returns.
159+
160Use complete sentences, starting with a capital letter and ending with
161a period, when writing conditions. Use the present tense. If there's a
162conditional part, put it in bold at the beginning of the sentence.
163+
164If the condition is too long for a single line, continue on the
165following line, after a tab.
166+
167Examples:
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+
178IMPORTANT: You should use aliases when possible to avoid duplication.
179See 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+
185The 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+
198This is a way for you to inform the reader about other existing, related
199functions, macros, or any other documentation. Keep in mind that the
200reader does not always know where to look for things.
201+
202If the description is too long for a single line, continue on the
203following 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
218The ultimate goal of the Babeltrace C API documentation is to make the
219layman write code using this API as fast as possible without having to
220ask for help. For this purpose, the documentation should always be as
221clear as possible, just like the function and type names try to be.
222
223Do not hesitate to repeat technical terms, even in the same sentence, if
224needed. For example, if you document a _value object_, then always use
225the term _value object_ in the documentation, not _value_, nor _object_,
226since they are ambiguous.
227
228You can use light emphasis to show the importance of a part of the text
229with the
230https://www.stack.nl/\~dimitri/doxygen/manual/commands.html#cmdem[`\em`]
231command (one word) or by surrounding the text to emphasize with `<em>`
232and `</em>`. Likewise, you can use strong emphasis when needed with the
233https://www.stack.nl/\~dimitri/doxygen/manual/commands.html#cmdb[`\b`]
234command (one word) or with `<strong>`/`</strong>`. In general, prefer
235light emphasis to strong emphasis.
236
237Links to other parts of the documentation are very important. Consider
238that the reader never knows that other functions exist other than the
239current one. Use as many internal links as possible. Use the following
240forms 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+
254Example:
255+
256--
257----
258You can create a \link events CTF IR event\endlink using [...]
259By calling \link func() said function\endlink, [...]
260----
261--
262+
263--
264[NOTE]
265.Doxygen limitation.
266====
267Do not put a space between the end of the text and the `\endlink`
268command, because this space becomes part of the hyperlink's text.
269
270Do _not_ do:
271
272----
273You can create a \link events CTF IR event \endlink using [...]
274By calling \link func() said function \endlink, [...]
275----
276====
277--
278
279See Doxygen's
280https://www.stack.nl/\~dimitri/doxygen/manual/autolink.html[Automatic
281link generation] for other ways to create automatic links.
282
283Try to follow as much as possible the
284https://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
302Here are the official names of the Babeltrace objects that you must use
303as 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
351Note that once you mention _CTF IR_ in an object name, you can omit
352it in the few following paragraphs.
This page took 0.037904 seconds and 4 git commands to generate.