Commit 553aa3c1 authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab Committed by Jonathan Corbet

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: default avatarMauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
parent fc275bf3
......@@ -258,6 +258,30 @@ named ``Return``.
as a new section heading, with probably won't produce the desired
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
-------------------------------
......@@ -331,30 +355,6 @@ cross-references.
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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment