Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
docs: kernel-doc.rst: improve function documentation section
Move its contents to happen earlier and improve the description
of return values, adding a subsection to it. Most of the contents
there came from kernel-doc-nano-HOWTO.txt.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
authored by
Mauro Carvalho Chehab
and committed by
Jonathan Corbet
fc275bf3
01f2c180
+61
-39
+61
-39
Documentation/doc-guide/kernel-doc.rst
+61
-39
Documentation/doc-guide/kernel-doc.rst
···
197
197
int d;
198
198
};
199
199
200
+
Function documentation
201
+
----------------------
202
+
203
+
The general format of a function and function-like macro kernel-doc comment is::
204
+
205
+
/**
206
+
* function_name() - Brief description of function.
207
+
* @arg1: Describe the first argument.
208
+
* @arg2: Describe the second argument.
209
+
* One can provide multiple line descriptions
210
+
* for arguments.
211
+
*
212
+
* A longer description, with more discussion of the function function_name()
213
+
* that might be useful to those using or modifying it. Begins with an
214
+
* empty comment line, and may include additional embedded empty
215
+
* comment lines.
216
+
*
217
+
* The longer description may have multiple paragraphs.
218
+
*
219
+
* Return: Describe the return value of foobar.
220
+
*
221
+
* The return value description can also have multiple paragraphs, and should
222
+
* be placed at the end of the comment block.
223
+
*/
224
+
225
+
The brief description following the function name may span multiple lines, and
226
+
ends with an argument description, a blank comment line, or the end of the
227
+
comment block.
228
+
229
+
Return values
230
+
~~~~~~~~~~~~~
231
+
232
+
The return value, if any, should be described in a dedicated section
233
+
named ``Return``.
234
+
235
+
.. note::
236
+
237
+
#) The multi-line descriptive text you provide does *not* recognize
238
+
line breaks, so if you try to format some text nicely, as in::
239
+
240
+
* Return:
241
+
* 0 - OK
242
+
* -EINVAL - invalid argument
243
+
* -ENOMEM - out of memory
244
+
245
+
this will all run together and produce::
246
+
247
+
Return: 0 - OK -EINVAL - invalid argument -ENOMEM - out of memory
248
+
249
+
So, in order to produce the desired line breaks, you need to use a
250
+
ReST list, e. g.::
251
+
252
+
* Return:
253
+
* * 0 - OK to runtime suspend the device
254
+
* * -EBUSY - Device should not be runtime suspended
255
+
256
+
#) If the descriptive text you provide has lines that begin with
257
+
some phrase followed by a colon, each of those phrases will be taken
258
+
as a new section heading, with probably won't produce the desired
259
+
effect.
260
+
200
261
201
262
Highlights and cross-references
202
263
-------------------------------
···
330
269
331
270
For further details, please refer to the `Sphinx C Domain`_ documentation.
332
271
333
-
Function documentation
334
-
----------------------
335
-
336
-
The general format of a function and function-like macro kernel-doc comment is::
337
-
338
-
/**
339
-
* function_name() - Brief description of function.
340
-
* @arg1: Describe the first argument.
341
-
* @arg2: Describe the second argument.
342
-
* One can provide multiple line descriptions
343
-
* for arguments.
344
-
*
345
-
* A longer description, with more discussion of the function function_name()
346
-
* that might be useful to those using or modifying it. Begins with an
347
-
* empty comment line, and may include additional embedded empty
348
-
* comment lines.
349
-
*
350
-
* The longer description may have multiple paragraphs.
351
-
*
352
-
* Return: Describe the return value of foobar.
353
-
*
354
-
* The return value description can also have multiple paragraphs, and should
355
-
* be placed at the end of the comment block.
356
-
*/
357
-
358
-
The brief description following the function name may span multiple lines, and
359
-
ends with an ``@argument:`` description, a blank comment line, or the end of the
360
-
comment block.
361
-
362
-
The kernel-doc function comments describe each parameter to the function, in
363
-
order, with the ``@argument:`` descriptions. The ``@argument:`` descriptions
364
-
must begin on the very next line following the opening brief function
365
-
description line, with no intervening blank comment lines. The ``@argument:``
366
-
descriptions may span multiple lines. The continuation lines may contain
367
-
indentation. If a function parameter is ``...`` (varargs), it should be listed
368
-
in kernel-doc notation as: ``@...:``.
369
-
370
-
The return value, if any, should be described in a dedicated section at the end
371
-
of the comment starting with "Return:".
372
272
373
273
Structure, union, and enumeration documentation
374
274
-----------------------------------------------