Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
docs: kernel-doc.rst: improve structs chapter
There is a mess on this chapter: it suggests that even
enums and unions should be documented with "struct". That's
not the way it should be ;-)
Fix it and move it to happen earlier.
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
553aa3c1
fc275bf3
+24
-24
+24
-24
Documentation/doc-guide/kernel-doc.rst
+24
-24
Documentation/doc-guide/kernel-doc.rst
···
258
258
as a new section heading, with probably won't produce the desired
259
259
effect.
260
260
261
+
Structure, union, and enumeration documentation
262
+
-----------------------------------------------
263
+
264
+
The general format of a struct, union, and enum kernel-doc comment is::
265
+
266
+
/**
267
+
* struct struct_name - Brief description.
268
+
* @argument: Description of member member_name.
269
+
*
270
+
* Description of the structure.
271
+
*/
272
+
273
+
On the above, ``struct`` is used to mean structs. You can also use ``union``
274
+
and ``enum`` to describe unions and enums. ``argument`` is used
275
+
to mean struct and union member names as well as enumerations in an enum.
276
+
277
+
The brief description following the structure name may span multiple lines, and
278
+
ends with a member description, a blank comment line, or the end of the
279
+
comment block.
280
+
281
+
The kernel-doc data structure comments describe each member of the structure,
282
+
in order, with the member descriptions.
283
+
284
+
261
285
262
286
Highlights and cross-references
263
287
-------------------------------
···
355
331
For further details, please refer to the `Sphinx C Domain`_ documentation.
356
332
357
333
358
-
Structure, union, and enumeration documentation
359
-
-----------------------------------------------
360
-
361
-
The general format of a struct, union, and enum kernel-doc comment is::
362
-
363
-
/**
364
-
* struct struct_name - Brief description.
365
-
* @member_name: Description of member member_name.
366
-
*
367
-
* Description of the structure.
368
-
*/
369
-
370
-
Below, "struct" is used to mean structs, unions and enums, and "member" is used
371
-
to mean struct and union members as well as enumerations in an enum.
372
-
373
-
The brief description following the structure name may span multiple lines, and
374
-
ends with a ``@member:`` description, a blank comment line, or the end of the
375
-
comment block.
376
-
377
-
The kernel-doc data structure comments describe each member of the structure, in
378
-
order, with the ``@member:`` descriptions. The ``@member:`` descriptions must
379
-
begin on the very next line following the opening brief function description
380
-
line, with no intervening blank comment lines. The ``@member:`` descriptions may
381
-
span multiple lines. The continuation lines may contain indentation.
382
334
383
335
In-line member documentation comments
384
336
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~