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>
This commit is contained in:
parent
fc275bf3b9
commit
553aa3c12e
@ -258,6 +258,30 @@ named ``Return``.
|
|||||||
as a new section heading, with probably won't produce the desired
|
as a new section heading, with probably won't produce the desired
|
||||||
effect.
|
effect.
|
||||||
|
|
||||||
|
Structure, union, and enumeration documentation
|
||||||
|
-----------------------------------------------
|
||||||
|
|
||||||
|
The general format of a struct, union, and enum kernel-doc comment is::
|
||||||
|
|
||||||
|
/**
|
||||||
|
* struct struct_name - Brief description.
|
||||||
|
* @argument: Description of member member_name.
|
||||||
|
*
|
||||||
|
* Description of the structure.
|
||||||
|
*/
|
||||||
|
|
||||||
|
On the above, ``struct`` is used to mean structs. You can also use ``union``
|
||||||
|
and ``enum`` to describe unions and enums. ``argument`` is used
|
||||||
|
to mean struct and union member names as well as enumerations in an enum.
|
||||||
|
|
||||||
|
The brief description following the structure name may span multiple lines, and
|
||||||
|
ends with a member description, a blank comment line, or the end of the
|
||||||
|
comment block.
|
||||||
|
|
||||||
|
The kernel-doc data structure comments describe each member of the structure,
|
||||||
|
in order, with the member descriptions.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
Highlights and cross-references
|
Highlights and cross-references
|
||||||
-------------------------------
|
-------------------------------
|
||||||
@ -331,30 +355,6 @@ cross-references.
|
|||||||
For further details, please refer to the `Sphinx C Domain`_ documentation.
|
For further details, please refer to the `Sphinx C Domain`_ documentation.
|
||||||
|
|
||||||
|
|
||||||
Structure, union, and enumeration documentation
|
|
||||||
-----------------------------------------------
|
|
||||||
|
|
||||||
The general format of a struct, union, and enum kernel-doc comment is::
|
|
||||||
|
|
||||||
/**
|
|
||||||
* struct struct_name - Brief description.
|
|
||||||
* @member_name: Description of member member_name.
|
|
||||||
*
|
|
||||||
* Description of the structure.
|
|
||||||
*/
|
|
||||||
|
|
||||||
Below, "struct" is used to mean structs, unions and enums, and "member" is used
|
|
||||||
to mean struct and union members as well as enumerations in an enum.
|
|
||||||
|
|
||||||
The brief description following the structure name may span multiple lines, and
|
|
||||||
ends with a ``@member:`` description, a blank comment line, or the end of the
|
|
||||||
comment block.
|
|
||||||
|
|
||||||
The kernel-doc data structure comments describe each member of the structure, in
|
|
||||||
order, with the ``@member:`` descriptions. The ``@member:`` descriptions must
|
|
||||||
begin on the very next line following the opening brief function description
|
|
||||||
line, with no intervening blank comment lines. The ``@member:`` descriptions may
|
|
||||||
span multiple lines. The continuation lines may contain indentation.
|
|
||||||
|
|
||||||
In-line member documentation comments
|
In-line member documentation comments
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
Loading…
Reference in New Issue
Block a user