908ae13b18
docs: kdoc_output: add support to handle code blocks
...
It is common to have code blocks inside kernel-doc markups.
By default, troff will group all lines altogether, producing a
very weird output. If a code block is detected by disabling
filling inside code blocks, re-enabling it afterwards.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org >
Signed-off-by: Jonathan Corbet <corbet@lwn.net >
Message-ID: <fb6f16ad345f7ec1b1ebe4c5ec7ea3d9cd6de4fb.1772810752.git.mchehab+huawei@kernel.org >
2026-03-09 10:34:39 -06:00
4ec130cff6
docs: kdoc_output: add a logic to handle tables inside kernel-doc markups
...
specially when DOC is used, it is not uncommon to have tables
inside a kernel-doc markup.
Add support for simple tables and complex grid tables when output
in groff format.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org >
Signed-off-by: Jonathan Corbet <corbet@lwn.net >
Message-ID: <442ad76442c325044eb9f34a155d5f484341fb35.1772810752.git.mchehab+huawei@kernel.org >
2026-03-09 10:34:38 -06:00
cde7c96f88
docs: kdoc_output: Change the logic to handle man highlight
...
The code inside ManFormat code to output man pages is too simple:
it produces very bad results when the content has tables or code
blocks.
Change the way lines are parsed there to allow adding extra
logic to handle some special cases.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org >
Signed-off-by: Jonathan Corbet <corbet@lwn.net >
Message-ID: <6ae2301a40b3fcb4381dd9dda8c75d14f9616b46.1772810752.git.mchehab+huawei@kernel.org >
2026-03-09 10:34:38 -06:00
e4dadcf510
docs: kdoc_output: pick a better default for modulename
...
Instead of placing the same data for modulename for all generated
man pages, use the directory from the filename used to produce
kernel docs as basis.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org >
Signed-off-by: Jonathan Corbet <corbet@lwn.net >
Message-ID: <8a5d91c93c0b9b34c2f60e389f4464742804d0d6.1772810752.git.mchehab+huawei@kernel.org >
2026-03-09 10:34:38 -06:00
26b4fdefc0
docs: kdoc_output: describe the class init parameters
...
As this class is part of the ABI used by both Sphinx kerneldoc
extension and docs/tools/kernel-doc, better describe what
parmeters are used to initialize ManOutput class.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org >
Signed-off-by: Jonathan Corbet <corbet@lwn.net >
Message-ID: <7c57f26150aae11fced259f30898a980b96efb68.1772810752.git.mchehab+huawei@kernel.org >
2026-03-09 10:34:38 -06:00
4160533d05
docs: kdoc_output: fix naming for DOC markups
...
Right now, DOC markups aren't being handled properly, as it was
using the same name for all output.
Fix it by filling the title argument on a different way.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org >
Signed-off-by: Jonathan Corbet <corbet@lwn.net >
Message-ID: <11d809e5c4bec23240d3ace3f342dbb2a9263446.1772810752.git.mchehab+huawei@kernel.org >
2026-03-09 10:34:38 -06:00
1a63342a27
docs: kdoc_output: don't use a different modulename for functions
...
It doesn't make much sense to have a different modulename just
for functions, but not for structs/enums/...
Use the same header everywere.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org >
Signed-off-by: Jonathan Corbet <corbet@lwn.net >
Message-ID: <978259bdf3e8d310c646ecf76ce56d054f6d5738.1772810752.git.mchehab+huawei@kernel.org >
2026-03-09 10:34:38 -06:00
31938f120f
docs: kdoc_output: use a single manual for everything
...
There's no reason why functions will be on a different manual.
Unify its name, calling it as "Kernel API Manual".
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org >
Signed-off-by: Jonathan Corbet <corbet@lwn.net >
Message-ID: <000e1174a551e97ad4710ad4f3750b22017bedd5.1772810752.git.mchehab+huawei@kernel.org >
2026-03-09 10:34:38 -06:00
43874045fa
docs: kdoc_output: remove extra attribute on man .TH headers
...
According with modern documents, groff .TH supports up to 5
arguments, but the logic passes 6. Drop the lastest one
("LINUX").
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org >
Signed-off-by: Jonathan Corbet <corbet@lwn.net >
Message-ID: <f5e480af877903b0596b6a56ef7a152eb8a10dbf.1772810752.git.mchehab+huawei@kernel.org >
2026-03-09 10:34:38 -06:00
c1873e7743
docs: kdoc_output: use a method to emit the .TH header
...
All man emit functions need to add a .TH header. Move the code
to a common function, as we'll be addressing some issues at
the common code.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org >
Signed-off-by: Jonathan Corbet <corbet@lwn.net >
Message-ID: <2e55fcfe8724fde08a78635a1a3f8b449a6adf82.1772810752.git.mchehab+huawei@kernel.org >
2026-03-09 10:34:38 -06:00
0d3ab0e4bb
docs: kdoc_files: document KernelFiles() ABI
...
The KernelFiles is the main entry point to run kernel-doc,
being used by both tools/docs/kernel-doc and
Documentation/sphinx/kerneldoc.py.
It is also used on QEMU, which also uses the kernel-doc
libraries from tools/lib/python/kdoc.
Properly describe its ABI contract.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org >
Signed-off-by: Jonathan Corbet <corbet@lwn.net >
Message-ID: <13eb44c341232564eaf2a9c9de4782369fef57e1.1772810574.git.mchehab+huawei@kernel.org >
2026-03-09 10:23:20 -06:00
861dcdb6ad
docs: kdoc_files: allows the caller to use a different xforms class
...
While the main goal for kernel-doc is to be used inside the Linux
Kernel, other open source projects could benefit for it. That's
currently the case of QEMU, which has a fork, mainly due to two
reasons:
- they need an extra C function transform rule;
- they handle the html output a little bit different.
Add an extra optional argument to make easier for the code to be
shared, as, with that, QEMU can just create a new derivated class
that will contain its specific rulesets, and just copy the
remaining kernel-doc files as-is.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org >
Signed-off-by: Jonathan Corbet <corbet@lwn.net >
Message-ID: <6b274ddbdcd9d438c6848e00e410a2f65ef80ec2.1772810574.git.mchehab+huawei@kernel.org >
2026-03-09 10:23:20 -06:00
85c2a51357
docs: kdoc_parser: move nested match transforms to xforms_lists.py
...
As NestedMatch now has a sub method and a declaration close to
what KernRe does, we can move the rules to xforms_lists and
simplify kdoc_parser a little bit.
No functional changes.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org >
Signed-off-by: Jonathan Corbet <corbet@lwn.net >
Message-ID: <762ce2a58ff024c1b0b6f6a6e05020d1415b8308.1772469446.git.mchehab+huawei@kernel.org >
2026-03-03 10:47:25 -07:00
fc44c0a0b2
docs: kdoc_re: make NestedMatch use KernRe
...
Instead of using re_compile, let's create the class with the
regex and use KernRe to keep it cached.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org >
Reviewed-by: Aleksandr Loktionov <aleksandr.loktionov@intel.com >
Signed-off-by: Jonathan Corbet <corbet@lwn.net >
Message-ID: <cdf900faf0ed8a08f8c6ac1db5a43342968c0739.1772469446.git.mchehab+huawei@kernel.org >
2026-03-03 10:47:25 -07:00
34503b5fd1
docs: kdoc_re: Change NestedMath args replacement to \0
...
Future patches will allow parsing each argument instead of the
hole set. Prepare for it by changing the replace all args from
\1 to \0.
No functional changes.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org >
Reviewed-by: Aleksandr Loktionov <aleksandr.loktionov@intel.com >
Signed-off-by: Jonathan Corbet <corbet@lwn.net >
Message-ID: <46e383118be9d9e432e3814fe819ebb12261d7b4.1772469446.git.mchehab+huawei@kernel.org >
2026-03-03 10:47:25 -07:00
962bdc440d
docs: kdoc_re: don't recompile NestedMatch regex every time
...
Store delimiters and its regex-compiled version as const vars.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org >
Reviewed-by: Aleksandr Loktionov <aleksandr.loktionov@intel.com >
Signed-off-by: Jonathan Corbet <corbet@lwn.net >
Message-ID: <0cf2b72d4785aa8b727188b56688ff442d1c65ce.1772469446.git.mchehab+huawei@kernel.org >
2026-03-03 10:47:25 -07:00
134468b0e2
docs: kdoc_re: handle strings and escape chars on NextMatch
...
The logic inside NestedMatch currently doesn't consider that
function arguments may have chars and strings, which may
eventually contain delimiters.
Add logic to handle strings and escape characters on them.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org >
Reviewed-by: Aleksandr Loktionov <aleksandr.loktionov@intel.com >
Signed-off-by: Jonathan Corbet <corbet@lwn.net >
Message-ID: <ac25335bc2d09649e17d1c86c17d3f8f2e8ec27c.1772469446.git.mchehab+huawei@kernel.org >
2026-03-03 10:47:25 -07:00
4ff59bdd93
docs: xforms_lists: ignore context analysis and lock attributes
...
Drop context analysis and lock (tracking) attributes to avoid
kernel-doc warnings.
There are now lots of warnings like these:
Documentation/core-api/kref:328: ../include/linux/kref.h:72: WARNING: Invalid C declaration: Expected end of definition. [error at 96]
int kref_put_mutex (struct kref *kref, void (*release)(struct kref *kref), struct mutex *mutex) __cond_acquires(true# mutex)
------------------------------------------------------------------------------------------------^
Documentation/core-api/kref:328: ../include/linux/kref.h:94: WARNING: Invalid C declaration: Expected end of definition. [error at 92]
int kref_put_lock (struct kref *kref, void (*release)(struct kref *kref), spinlock_t *lock) __cond_acquires(true# lock)
--------------------------------------------------------------------------------------------^
The regex is suggested by Mauro; mine was too greedy. Thanks.
Updated context analysis and lock macros list provided by PeterZ. Thanks.
[mchehab: modified to be applied after xforms_lists split]
Reported-by: Stephen Rothwell <sfr@canb.auug.org.au >
Closes: https://lore.kernel.org/all/20260107161548.45530e1c@canb.auug.org.au/
Signed-off-by: Randy Dunlap <rdunlap@infradead.org >
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org >
Reviewed-by: Aleksandr Loktionov <aleksandr.loktionov@intel.com >
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org >
Signed-off-by: Jonathan Corbet <corbet@lwn.net >
Message-ID: <3c7fdfc364a8920f92530b47bdbf4bb29a40371f.1772469446.git.mchehab+huawei@kernel.org >
2026-03-03 10:47:25 -07:00
d842057c4a
docs: kdoc_parser: move transform lists to a separate file
...
Over the time, most of the changes at kernel-doc are related
to maintaining a list of transforms to convert macros into pure
C code.
Place such transforms on a separate module, to cleanup the
parser module.
There is an advantage on that: QEMU also uses our own kernel-doc,
but the xforms list there is different. By placing it on a
separate module, we can minimize the differences and make it
easier to keep QEMU in sync with Kernel upstream.
No functional changes.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org >
Reviewed-by: Aleksandr Loktionov <aleksandr.loktionov@intel.com >
Signed-off-by: Jonathan Corbet <corbet@lwn.net >
Message-ID: <ccd74b7589e1fff340a74bf8ed16a974532cb54f.1772469446.git.mchehab+huawei@kernel.org >
2026-03-03 10:47:25 -07:00
95a9429cc6
docs: kdoc_re: better show KernRe() at documentation
...
the __repr__() function is used by autodoc to document macro
initialization.
Add a better representation for them.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org >
Reviewed-by: Aleksandr Loktionov <aleksandr.loktionov@intel.com >
Signed-off-by: Jonathan Corbet <corbet@lwn.net >
Message-ID: <80d27732368c14125c1b76048a70d8b4aee527ef.1772469446.git.mchehab+huawei@kernel.org >
2026-03-03 10:47:25 -07:00
97d4e70bc2
docs: kdoc_parser: handle struct member macro VIRTIO_DECLARE_FEATURES(name)
...
Parse the macro VIRTIO_DECLARE_FEATURES(name) and expand it to its
definition. These prevents one build warning:
WARNING: include/linux/virtio.h:188 struct member 'VIRTIO_DECLARE_FEATURES(features' not described in 'virtio_device'
Signed-off-by: Randy Dunlap <rdunlap@infradead.org >
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org >
Reviewed-by: Aleksandr Loktionov <aleksandr.loktionov@intel.com >
Signed-off-by: Jonathan Corbet <corbet@lwn.net >
Message-ID: <6f62e1f1210e74906fa50f4e937f66f54813661b.1772469446.git.mchehab+huawei@kernel.org >
2026-03-03 10:47:24 -07:00
9bff5121fe
docs: kdoc_parser: add support for LIST_HEAD
...
Convert LIST_HEAD into struct list_head when handling its
prototype.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org >
Acked-by: Randy Dunlap <rdunlap@infradead.org >
Tested-by: Randy Dunlap <rdunlap@infradead.org >
Reviewed-by: Aleksandr Loktionov <aleksandr.loktionov@intel.com >
Signed-off-by: Jonathan Corbet <corbet@lwn.net >
Message-ID: <8bdfa6ba6002b0a73a83660f0ce7b40e30124552.1772469446.git.mchehab+huawei@kernel.org >
2026-03-03 10:47:24 -07:00
6d9c2e9575
docs: kdoc_parser: fix parser to support multi-word types
...
The regular expression currently expects a single word for the
type, but it may be something like "struct foo".
Add support for it.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org >
Acked-by: Randy Dunlap <rdunlap@infradead.org >
Tested-by: Randy Dunlap <rdunlap@infradead.org >
Reviewed-by: Aleksandr Loktionov <aleksandr.loktionov@intel.com >
Signed-off-by: Jonathan Corbet <corbet@lwn.net >
Message-ID: <544c73a9e670b6fef1828bf4f2ba0de7d29d8675.1772469446.git.mchehab+huawei@kernel.org >
2026-03-03 10:47:24 -07:00
b7dc635459
docs: kdoc_parser: don't exclude defaults from prototype
...
If we do that, the defaults won't be parsed.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org >
Acked-by: Randy Dunlap <rdunlap@infradead.org >
Tested-by: Randy Dunlap <rdunlap@infradead.org >
Reviewed-by: Aleksandr Loktionov <aleksandr.loktionov@intel.com >
Signed-off-by: Jonathan Corbet <corbet@lwn.net >
Message-ID: <cedf2a819846d2f082388e9ba3d95047c35df6fd.1772469446.git.mchehab+huawei@kernel.org >
2026-03-03 10:47:24 -07:00
9bbf22b87d
docs: kdoc_parser: fix the default_value logic for variables
...
The indentation is wrong for the second regex, which causes
problems on variables with defaults.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org >
Acked-by: Randy Dunlap <rdunlap@infradead.org >
Tested-by: Randy Dunlap <rdunlap@infradead.org >
Reviewed-by: Aleksandr Loktionov <aleksandr.loktionov@intel.com >
Signed-off-by: Jonathan Corbet <corbet@lwn.net >
Message-ID: <681f18338abd6ae33cb9c15d72bb31a1cba75a9a.1772469446.git.mchehab+huawei@kernel.org >
2026-03-03 10:47:24 -07:00
4fd349f03d
docs: kdoc_parser: fix variable regexes to work with size_t
...
The regular expressions meant to pick variable types are too
naive: they forgot that the type word may contain underlines.
It also means that we need to change the regex which detects
var attributes to handle "const".
Co-developed-by: Randy Dunlap <rdunlap@infradead.org >
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org >
Acked-by: Randy Dunlap <rdunlap@infradead.org >
Tested-by: Randy Dunlap <rdunlap@infradead.org >
Reviewed-by: Aleksandr Loktionov <aleksandr.loktionov@intel.com >
Signed-off-by: Jonathan Corbet <corbet@lwn.net >
Message-ID: <8230715239929cf9d475ab81ca1df7de65d82d06.1772469446.git.mchehab+huawei@kernel.org >
2026-03-03 10:47:24 -07:00
cca1bbdd72
docs: kdoc_parser: don't mangle with function defines
...
Mangling with #defines is not nice, as we may end removing
the macro names, preventing several macros from being properly
documented.
Also, on defines, we have something like:
#define foo(a1, a2, a3, ...) \
/* some real implementation */
The prototype part (first line on this example) won't contain
any macros, so no need to apply any regexes on it.
With that, move the apply_transforms() logic to ensure that
it will be called only on functions.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org >
Acked-by: Randy Dunlap <rdunlap@infradead.org >
Tested-by: Randy Dunlap <rdunlap@infradead.org >
Reviewed-by: Aleksandr Loktionov <aleksandr.loktionov@intel.com >
Signed-off-by: Jonathan Corbet <corbet@lwn.net >
Message-ID: <8f9854c8ca1c794b6a3fe418f7adbc32aa68b432.1772469446.git.mchehab+huawei@kernel.org >
2026-03-03 10:47:24 -07:00
77e6e17e9f
docs: kdoc_parser: move var transformers to the beginning
...
Just like functions and structs had their transform variables
placed at the beginning, move variable transforms to there
as well.
No functional changes.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org >
Acked-by: Randy Dunlap <rdunlap@infradead.org >
Tested-by: Randy Dunlap <rdunlap@infradead.org >
Reviewed-by: Aleksandr Loktionov <aleksandr.loktionov@intel.com >
Signed-off-by: Jonathan Corbet <corbet@lwn.net >
Message-ID: <491b290252a308f381f88353a3bbe9e2bd1f6a62.1772469446.git.mchehab+huawei@kernel.org >
2026-03-03 10:47:24 -07:00
8eb49357ff
docs: kdoc_re: don't go past the end of a line
...
The logic which checks if the line ends with ";" is currently
broken: it may try to read past the buffer.
Fix it by checking before trying to access line[pos].
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org >
Acked-by: Randy Dunlap <rdunlap@infradead.org >
Tested-by: Randy Dunlap <rdunlap@infradead.org >
Reviewed-by: Aleksandr Loktionov <aleksandr.loktionov@intel.com >
Signed-off-by: Jonathan Corbet <corbet@lwn.net >
Message-ID: <bce51ba0260a053a0ec55a7375d6ed7a7c08026c.1772469446.git.mchehab+huawei@kernel.org >
2026-03-03 10:47:24 -07:00
2b144a30a4
docs: kdoc_re: add support for groups()
...
Add an equivalent to re groups() method.
This is useful on debug messages.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org >
Acked-by: Randy Dunlap <rdunlap@infradead.org >
Tested-by: Randy Dunlap <rdunlap@infradead.org >
Reviewed-by: Aleksandr Loktionov <aleksandr.loktionov@intel.com >
Signed-off-by: Jonathan Corbet <corbet@lwn.net >
Message-ID: <20d1a9c77200e28cc2ff1d6122635c43f8ba6a71.1772469446.git.mchehab+huawei@kernel.org >
2026-03-03 10:47:24 -07:00
b211a30690
docs: kdoc_parser: allow __exit in function prototypes
...
Handle functions that are marked with __exit to prevent warnings:
Documentation/networking/iucv:35: ../net/iucv/iucv.c:1918: WARNING: Error in declarator or parameters
Invalid C declaration: Expecting "(" in parameters. [error at 12]
void __exit iucv_exit (void)
------------^
Signed-off-by: Randy Dunlap <rdunlap@infradead.org >
Reviewed-by: Mauro Carvalho Chehab <mchehab@kernel.org >
Signed-off-by: Jonathan Corbet <corbet@lwn.net >
Message-ID: <20260206065440.2412185-1-rdunlap@infradead.org >
2026-02-09 12:46:28 -07:00
98f51c466a
docs: kdoc: Fix pdfdocs build for tools
...
the "\1" inside a docstring requires proper scaping to not be
considered a hex character and break the build.
Reported-by: Akira Yokosawa <akiyks@gmail.com >
Closes: https://lore.kernel.org/linux-doc/63e99049-cc72-4156-83af-414fdde34312@gmail.com/
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org >
Signed-off-by: Jonathan Corbet <corbet@lwn.net >
Message-ID: <2fff8ef1d0d64e8b68f15f5c07613f302d773855.1769500383.git.mchehab+huawei@kernel.org >
2026-02-02 09:57:46 -07:00
330367bdc1
Merge branch 'mauro' into docs-mw
...
Mauro's work to include documentation from our Python modules. His cover
letter follows:
This is an extended version of:
https://lore.kernel.org/linux-doc/cover.1768488832.git.mchehab+huawei@kernel.org/
It basically adds everything we currently have inside libs/tool/python
to "tools" book inside documentation.
This version should be independent of the other series yet to be merged,
(including the jobserver one).
The vast amount of changes here are docstring cleanups and additions.
They mainly consists on:
- ensuring that every phrase will end with a period, making it uniform
along all files;
- cleaning ups to better uniform docstrings;
- variable descriptions now use "#:" markup, as it allows autodoc to
add them inside the documentation;
- added some missing docstrings;
- some new blank lines at comments to make ReST syntax parser happy;
- add a couple of sphinx markups (mainly, code blocks).
Most of those are minor changes, affecting only comments.
It also has one patch per libarary type, adding them to docs.
For kernel-doc, I did the cleanups first, as there is one code block
inside tools/lib/python/kdoc/latex_fonts.py that would cause a Sphinx
crash without such markups.
The series actually starts with 3 fixes:
- avoid "*" markups on indexes with deep> 3 to override text
- a variable rename to stop abusing doctree name
- don't rely on cwd to get Documentation/ location
patch 4 adds support to document scripts either at:
- tools/
- scripts/
patch 5 contains a CSS to better display autodoc html output.
For those who want to play with documentation, documenting a python
file is very simple. All it takes is to use:
.. automodule:: lib.python.<dir+name>
Usually, we add a couple of control members to it to adjust
the desired documentation scope (add/remove members, showing class
inheritance, showing members that currently don't have
docstrings, etc). That's why we're using:
.. automodule:: lib.python.kdoc.enrich_formatter
:members:
:show-inheritance:
:undoc-members:
(and similar) inside tools/kdoc*.rst.
autodoc allows filtering in/out members, file docstrings, etc.
It also allows documenting just some members or functions with
directives like:
..autofunction:
..automember:
Sphinx also has a helper script to generate .rst files with
documentation:
$ sphinx-apidoc -o foobar tools/lib/python/
which can be helpful to discover what should be documented,
although changes are needed to use what it produces.
2026-01-23 11:46:08 -07:00
ef6aa110d8
docs: parse_features: make documentation more consistent
...
Do some changes to:
- add missing documentation strings to vars;
- add a missing docstring;
- ensure that phases will end with a period.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org >
Signed-off-by: Jonathan Corbet <corbet@lwn.net >
Message-ID: <3722f10361638561a5ced18cf4f409930c88270b.1768838938.git.mchehab+huawei@kernel.org >
2026-01-23 11:37:39 -07:00
8b85f614f3
docs: jobserver: do some documentation improvements
...
Make Sphinx handle better jobserver class documentation
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org >
Signed-off-by: Jonathan Corbet <corbet@lwn.net >
Message-ID: <18a9c1406bdead680e3ee5768c97ae8b2138e8ea.1768838938.git.mchehab+huawei@kernel.org >
2026-01-23 11:37:39 -07:00
b713adadf8
docs: kabi: helpers: add documentation for each "enum" value
...
Ensure that kABI module documentation will describe each
debug bit.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org >
Signed-off-by: Jonathan Corbet <corbet@lwn.net >
Message-ID: <3b118b157e52d757bf82fd74f03b0f4bd9e8b8f1.1768838938.git.mchehab+huawei@kernel.org >
2026-01-23 11:37:39 -07:00
5c9ece0b02
docs: kabi: helpers: add helper for debug bits 7 and 8
...
The kabi logic supports 8 debug bits, but only 6 are currently
documented. Document the remaining ones.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org >
Signed-off-by: Jonathan Corbet <corbet@lwn.net >
Message-ID: <60e99b9060396eac8621954d6b8a73af45df90fb.1768838938.git.mchehab+huawei@kernel.org >
2026-01-23 11:37:39 -07:00
a50c62d375
docs: kabi: system_symbols: end docstring phrases with a dot
...
Some docstring classes are not ending with a dot. Fix to make it
more uniform.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org >
Signed-off-by: Jonathan Corbet <corbet@lwn.net >
Message-ID: <efd0e150d8e12d8ea2665f54a96b1997f32897b7.1768838938.git.mchehab+huawei@kernel.org >
2026-01-23 11:37:39 -07:00
ff91637dec
docs: python: abi_regex: do some improvements at documentation
...
Add documentation for two consts and ensure that all sentenses
will end with a dot.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org >
Signed-off-by: Jonathan Corbet <corbet@lwn.net >
Message-ID: <5419ad89a5042c1571198c2f055866674808579b.1768838938.git.mchehab+huawei@kernel.org >
2026-01-23 11:37:39 -07:00
66c3bf974d
docs: python: abi_parser: do some improvements at documentation
...
Add documentation for two consts and ensure that all sentenses
will end with a dot.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org >
Signed-off-by: Jonathan Corbet <corbet@lwn.net >
Message-ID: <c5756d7fd70697890130b41b2856c59144d01844.1768838938.git.mchehab+huawei@kernel.org >
2026-01-23 11:37:38 -07:00
33220c1fc1
docs: kdoc: python_version: Improve docstrings and comments
...
In preparation to document kernel-doc module, improve its
documentation.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org >
Signed-off-by: Jonathan Corbet <corbet@lwn.net >
Message-ID: <2153afaeb496e1bb8d3cc318fff26c3f99d99486.1768838938.git.mchehab+huawei@kernel.org >
2026-01-23 11:37:38 -07:00
7ef684c9fd
docs: kdoc: enrich_formatter: Improve docstrings and comments
...
In preparation to document kernel-doc module, improve its
documentation.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org >
Signed-off-by: Jonathan Corbet <corbet@lwn.net >
Message-ID: <55ec8b896fe00529d326859cd094230fb5a2cd30.1768838938.git.mchehab+huawei@kernel.org >
2026-01-23 11:37:38 -07:00
e68c84b9f3
docs: kdoc: parse_data_structs: Improve docstrings and comments
...
In preparation to document kernel-doc module, improve its
documentation.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org >
Signed-off-by: Jonathan Corbet <corbet@lwn.net >
Message-ID: <76ead85b4c13a8038180a792e270c3691d26cd25.1768838938.git.mchehab+huawei@kernel.org >
2026-01-23 11:37:38 -07:00
b0b88915c8
docs: kdoc_re: Improve docstrings and comments
...
In preparation to document kernel-doc module, improve its
documentation.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org >
Signed-off-by: Jonathan Corbet <corbet@lwn.net >
Message-ID: <14a12a43144d52345bfd405d0401d246f0885acf.1768838938.git.mchehab+huawei@kernel.org >
2026-01-23 11:37:38 -07:00
245f1ab2c9
docs: kdoc_output: Improve docstrings and comments
...
In preparation to document kernel-doc module, improve its
documentation.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org >
Signed-off-by: Jonathan Corbet <corbet@lwn.net >
Message-ID: <ac03bf776f0929bbe822cd8269f2a31e275b8d6b.1768838938.git.mchehab+huawei@kernel.org >
2026-01-23 11:37:38 -07:00
50206750e0
docs: kdoc_parser: Improve docstrings and comments
...
In preparation to document kernel-doc module, improve its
documentation.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org >
Signed-off-by: Jonathan Corbet <corbet@lwn.net >
Message-ID: <b6aabe25b45e9751885becd544a4db82dbe11ff2.1768838938.git.mchehab+huawei@kernel.org >
2026-01-23 11:37:38 -07:00
f40bba94a4
docs: kdoc_item: Improve docstrings and comments
...
In preparation to document kernel-doc module, improve its
documentation.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org >
Signed-off-by: Jonathan Corbet <corbet@lwn.net >
Message-ID: <65a7c6bb318e7a8cbf5c115903d507568099151a.1768838938.git.mchehab+huawei@kernel.org >
2026-01-23 11:37:38 -07:00
8d08c7c6ff
docs: kdoc_files: Improve docstrings and comments
...
In preparation to document kernel-doc module, improve its
documentation.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org >
Signed-off-by: Jonathan Corbet <corbet@lwn.net >
Message-ID: <75d58878ad6f83f24f1c0ce9e04301a000ecbaa3.1768838938.git.mchehab+huawei@kernel.org >
2026-01-23 11:37:38 -07:00
4d7f6319fa
docs: kdoc: latex_fonts: Improve docstrings and comments
...
In preparation to document kernel-doc module, improve its
documentation.
Among the changes, it had to place the xml template inside
a code block, as otherwise doc build would break.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org >
Signed-off-by: Jonathan Corbet <corbet@lwn.net >
Message-ID: <6e0eb2e245eae9b4f39cf231dee32df00b9e8b7b.1768838938.git.mchehab+huawei@kernel.org >
2026-01-23 11:37:38 -07:00
11ba4215d0
Merge branch 'mauro' into docs-mw
...
A combination of Mauro's -Werror work and my long-belated kernel-doc move.
2026-01-20 16:13:23 -07:00
Mauro Carvalho Chehab
Randy Dunlap
Jonathan Corbet