Commit | Line | Data |
---|---|---|
3758cf40 PP |
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 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 | + | |
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. |