p71924506
/
linux_old1
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

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:
Mauro Carvalho Chehab 2017-12-18 10:30:05 -02:00 committed by Jonathan Corbet
parent fc275bf3b9
commit 553aa3c12e
1 changed files with 24 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

48
Documentation/doc-guide/kernel-doc.rst
View File

@ -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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~