linux-toradex.git/Documentation/doc-guide, branch master

docs: kernel-doc: inform that '@' applies to other fields

2026-09-15T19:02:10+00:00

The '@' sign applies to struct members, union members, and enum
values as well as function parameters. Document that.

Signed-off-by: Randy Dunlap 
Signed-off-by: Jonathan Corbet 
Message-ID: <20260911184213.4143776-1-rdunlap@infradead.org>

docs: kernel-doc: include "define" as an identifier type

2026-09-15T19:01:07+00:00

Update the list of identifier types to include "define", which was
added in 2014 in commit
cbb4d3e6510b ("scripts/kernel-doc: handle object-like macros")

Signed-off-by: Randy Dunlap 
Signed-off-by: Jonathan Corbet 
Message-ID: <20260912055202.103573-1-rdunlap@infradead.org>

docs: parse-headers: Fix script name and stale Makefile reference

2026-09-07T16:01:31+00:00

The script is tools/docs/parse-headers.py, not parse_headers.py, and its
FILE_RULES argument is optional. Commit 8a298579cdfc ("scripts:
sphinx-build-wrapper: get rid of uapi/media Makefile") removed the
Makefile the text points to as an example; the cross-references are now
generated by the kernel-include directive, so point to a file that uses
it.

Fixes: d69a03a97a2d ("docs: doc-guide: parse-headers.rst update its documentation")
Fixes: 8a298579cdfc ("scripts: sphinx-build-wrapper: get rid of uapi/media Makefile")
Assisted-by: LLM
Signed-off-by: Karl Mehltretter 
Acked-by: Randy Dunlap 
Signed-off-by: Jonathan Corbet 
Message-ID: <20260905025821.83968-1-kmehltretter@gmail.com>

docs: kernel-doc.rst: document private: scope propagation

2026-03-22T21:02:29+00:00

This was an undefined behavior, but at least one place used private:
inside a nested struct meant to not be propagated outside it.

Kernel-doc now defines how this is propagated. So, document that.

Signed-off-by: Mauro Carvalho Chehab 
Signed-off-by: Jonathan Corbet 
Message-ID:

Documentation: use a source-read extension for the index link boilerplate

2026-01-23T18:59:34+00:00

The root document usually has a special :ref:`genindex` link to the
generated index. This is also the case for Documentation/index.rst. The
other index.rst files deeper in the directory hierarchy usually don't.

For SPHINXDIRS builds, the root document isn't Documentation/index.rst,
but some other index.rst in the hierarchy. Currently they have a
".. only::" block to add the index link when doing SPHINXDIRS html
builds.

This is obviously very tedious and repetitive. The link is also added to
all index.rst files in the hierarchy for SPHINXDIRS builds, not just the
root document.

Put the boilerplate in a sphinx-includes/subproject-index.rst file, and
include it at the end of the root document for subproject builds in an
ad-hoc source-read extension defined in conf.py.

For now, keep having the boilerplate in translations, because this
approach currently doesn't cover translated index link headers.

Cc: Jonathan Corbet 
Cc: Mauro Carvalho Chehab 
Cc: Randy Dunlap 
Signed-off-by: Jani Nikula 
Tested-by: Mauro Carvalho Chehab 
Reviewed-by: Mauro Carvalho Chehab 
[jc: did s/doctree/kern_doc_dir/ ]
Signed-off-by: Jonathan Corbet 
Message-ID: <20260123143149.2024303-1-jani.nikula@intel.com>

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:

docs: parse-headers.rst: Fix a typo

2025-11-18T16:13:40+00:00

Replace "vantage" with "advantage" in the description of userspace API
cross-references.

Signed-off-by: Ankit Khushwaha 
Signed-off-by: Jonathan Corbet 
Message-ID: <20251115114233.32239-1-ankitkhushwaha.linux@gmail.com>