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

docs: kernel-doc.rst: better describe kernel-doc arguments 

Add a new section to describe kernel-doc arguments,
adding examples about how identation should happen, as failing
to do that causes Sphinx to do the wrong thing.

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:02 -02:00 committed by Jonathan Corbet
parent 012e93cbdb
commit 63ac85174a
1 changed files with 41 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -112,16 +112,17 @@ Example kernel-doc function comment::
/**
* foobar() - Brief description of foobar.
* @arg: Description of argument of foobar.
* @argument1: Description of parameter argument1 of foobar.
* @argument2: Description of parameter argument2 of foobar.
*
* Longer description of foobar.
*
* Return: Description of return value of foobar.
*/
int foobar(int arg)
int foobar(int argument1, char *argument2)
The format is similar for documentation for structures, enums, paragraphs,
etc. See the sections below for details.
etc. See the sections below for specific details of each type.
The kernel-doc structure is extracted from the comments, and proper `Sphinx C
Domain`_ function and type descriptions with anchors are generated for them. The
@ -130,6 +131,43 @@ cross-references. See below for details.
.. _Sphinx C Domain: http://www.sphinx-doc.org/en/stable/domains.html
Parameters and member arguments
-------------------------------
The kernel-doc function comments describe each parameter to the function and
function typedefs or each member of struct/union, in order, with the
``@argument:`` descriptions. For each non-private member argument, one
``@argument`` definition is needed.
The ``@argument:`` descriptions begin on the very next line following
the opening brief function description line, with no intervening blank
comment lines.
The ``@argument:`` descriptions may span multiple lines.
.. note::
If the ``@argument`` description has multiple lines, the continuation
of the description should be starting exactly at the same column as
the previous line, e. g.::
* @argument: some long description
* that continues on next lines
or::
* @argument:
* some long description
* that continues on next lines
If a function or typedef parameter argument is ``...`` (e. g. a variable
number of arguments), its description should be listed in kernel-doc
notation as::
* @...: description
Highlights and cross-references
-------------------------------