mirrors/linux
2
0
Fork 0
mirror of https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git synced 2026-08-31 08:15:07 -04:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
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>
This commit is contained in:
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
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); 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 Object-like macro documentation
------------------------------- -------------------------------
@@ -463,14 +475,18 @@ through the following syntax::
For further details, please refer to the `Sphinx C Domain`_ documentation. 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 Overview documentation comments
------------------------------- -------------------------------
To facilitate having source code and comments close together, you can include 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 documentation blocks that are free-form comments instead of being
kernel-doc for functions, structures, unions, enums, or typedefs. This could be kernel-doc for functions, structures, unions, enums, typedefs or variables.
used for something like a theory of operation for a driver or library code, for This could be used for something like a theory of operation for a driver or
example. library code, for example.
This is done by using a ``DOC:`` section keyword with a section title. 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*. Include documentation for each *function* and *type* in *source*.
If no *function* is specified, the documentation for all functions If no *function* is specified, the documentation for all functions
and types in the *source* will be included. 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:: Examples::