kernel/linux.git/Documentation/doc-guide/kernel-doc.rst, branch v7.0.10

docs: kdoc: move kernel-doc to tools/docs

2026-01-20T22:31:06+00:00

kernel-doc is the last documentation-related tool still living outside of the tools/docs directory; the time has come to move it over. [mchehab: fixed kdoc lib location] Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Message-ID: <311d17e403524349940a8b12de6b5e91e554b1f4.1768823489.git.mchehab+huawei@kernel.org>

doc-guide: kernel-doc: specify that W=n does not check header files

2026-01-06T21:42:31+00:00

The documentation states that: make W=n can be used to verify the documentation format. This is true for .c files but not for headers [1]. Modify the documentation to specify that headers files are not covered by make W=n and that these need to be checked separately with scripts/kernel-doc. [1] commit 3a025e1d1c2e ("Add optional check for bad kernel-doc comments") Link: https://git.kernel.org/torvalds/c/3a025e1d1c2e Signed-off-by: Vincent Mailhol Signed-off-by: Jonathan Corbet Message-ID: <20251225-doc-format-check-v1-1-dff637a4d275@kernel.org>

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

2025-12-22T21:43:25+00:00

Add a description containing the new syntax to document variables within kernel-doc markups. Reviewed-by: Randy Dunlap Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Jonathan Corbet Message-ID:

docs: kernel-doc.rst: don't let automarkup mangle with consts

2025-12-22T21:43:25+00:00

This document contains several words that tricks automarkup. Ensure that all of them will be inside a ``const`` markup, avoiding automarkup to touch them. Signed-off-by: Mauro Carvalho Chehab Reviewed-by: Randy Dunlap Signed-off-by: Jonathan Corbet Message-ID:

doc-guide: kernel-doc: add %CONST examples

2025-11-05T18:27:12+00:00

Add examples of using '%' for formatting constant values to facilitate more usage of "%CONST" in kernel-doc. Suggested-by: Tony Luck Signed-off-by: Randy Dunlap Signed-off-by: Jonathan Corbet Message-ID: <20251104050930.720711-1-rdunlap@infradead.org>

docs: add support to build manpages from kerneldoc output

2025-09-18T17:19:57+00:00

Generating man files currently requires running a separate script. The target also doesn't appear at the docs Makefile. Add support for mandocs at the Makefile, adding the build logic inside sphinx-build-wrapper, updating documentation and dropping the ancillary script. Signed-off-by: Mauro Carvalho Chehab Message-ID: <3d248d724e7f3154f6e3a227e5923d7360201de9.1758196090.git.mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet

Documentation: kernel-doc: enumerate identifier types

2024-11-22T17:37:40+00:00

Explain that a kernel-doc :identifiers: line can refer to a struct, union, enum, or typedef as well as functions. Signed-off-by: Randy Dunlap Cc: Jonathan Corbet Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20241119203201.110953-1-rdunlap@infradead.org

doc-guide: kernel-doc: document Returns: spelling

2024-05-30T19:35:07+00:00

scripts/kernel-doc accepts "Return:" or "Returns:" for describing the return value of a function or function-like macro, so document this alternative spelling and use it in an example. Signed-off-by: Randy Dunlap Suggested-by: Dmitry Baryshkov Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20240522224726.10498-1-rdunlap@infradead.org

doc-guide: kernel-doc: tell about object-like macros

2024-01-30T20:31:09+00:00

Since 2014 kernel-doc has supported describing object-like macros but it is not documented anywhere. I should have required some documentation for it when I merged the patch. :( There are currently only 3 uses of this (all in DRM headers, in include/drm/*.h). Add object-like macro kernel-doc documentation now so that more may know about it and use it. Fixes: cbb4d3e6510b ("scripts/kernel-doc: handle object-like macros") Signed-off-by: Randy Dunlap Cc: Jonathan Corbet Cc: linux-doc@vger.kernel.org Acked-by: Daniel Vetter Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20240107012400.32587-1-rdunlap@infradead.org

Documentation: doc-guide: use '%' constant indicator in Return: examples

2023-07-14T19:16:59+00:00

Use the 'constant' indicator '%' in the examples for the Return: values syntax. This can help encourage people to use it. Signed-off-by: Randy Dunlap Suggested-by: Steven Rostedt Cc: Jonathan Corbet Cc: linux-doc@vger.kernel.org Link: https://lore.kernel.org/lkml/20221121154358.36856ca6@gandalf.local.home/ Acked-by: Steven Rostedt (Google) Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20230703232030.8223-1-rdunlap@infradead.org