superrob1500
/
mirror-linux
mirror of https://github.com/torvalds/linux
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

docs: kernel-doc.rst: document the new "var" kernel-doc markup 

Add a description containing the new syntax to document
variables within kernel-doc markups.

Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <aa0e3abcd6882a62f3ab9c34033c60fca1c44604.1765894964.git.mchehab+huawei@kernel.org>
master
Mauro Carvalho Chehab 2025-12-16 15:26:16 +01:00 committed by Jonathan Corbet
parent 8deb5d725b
commit b580fa304c
1 changed files with 21 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -342,6 +342,18 @@ Typedefs with function prototypes can also be documented::
*/
typedef void (*type_name)(struct v4l2_ctrl *arg1, void *arg2);
Variables documentation
-----------------------
The general format of a kernel-doc variable comment is::
/**
* var var_name - Brief description.
*
* Description of the var_name variable.
*/
extern int var_name;
Object-like macro documentation
-------------------------------
@ -463,14 +475,18 @@ through the following syntax::
For further details, please refer to the `Sphinx C Domain`_ documentation.
.. note::
Variables aren't automatically cross referenced. For those, you need to
explicitly add a C domain cross-reference.
Overview documentation comments
-------------------------------
To facilitate having source code and comments close together, you can include
kernel-doc documentation blocks that are free-form comments instead of being
kernel-doc for functions, structures, unions, enums, or typedefs. This could be
used for something like a theory of operation for a driver or library code, for
example.
kernel-doc for functions, structures, unions, enums, typedefs or variables.
This could be used for something like a theory of operation for a driver or
library code, for example.
This is done by using a ``DOC:`` section keyword with a section title.
@ -538,7 +554,8 @@ identifiers: *[ function/type ...]*
Include documentation for each *function* and *type* in *source*.
If no *function* is specified, the documentation for all functions
and types in the *source* will be included.
*type* can be a ``struct``, ``union``, ``enum``, or ``typedef`` identifier.
*type* can be a ``struct``, ``union``, ``enum``, ``typedef`` or ``var``
identifier.
Examples::