| 4ff59bdd | 02-Mar-2026 |
Randy Dunlap <rdunlap@infradead.org> |
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:
Do
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>
show more ...
|
| d842057c | 02-Mar-2026 |
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> |
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
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>
show more ...
|
| 95a9429c | 02-Mar-2026 |
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> |
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 Carvalh
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>
show more ...
|
| 97d4e70b | 02-Mar-2026 |
Randy Dunlap <rdunlap@infradead.org> |
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:
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>
show more ...
|
| 9bff5121 | 02-Mar-2026 |
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> |
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 Du
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>
show more ...
|
| 6d9c2e95 | 02-Mar-2026 |
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> |
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.
Signe
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>
show more ...
|
| b7dc6354 | 02-Mar-2026 |
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> |
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 <rdunla
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>
show more ...
|
| 9bbf22b8 | 02-Mar-2026 |
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> |
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 <m
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>
show more ...
|
| 4fd349f0 | 02-Mar-2026 |
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> |
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
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>
show more ...
|
| cca1bbdd | 02-Mar-2026 |
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> |
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
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>
show more ...
|
| 77e6e17e | 02-Mar-2026 |
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> |
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 functi
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>
show more ...
|
| 8eb49357 | 02-Mar-2026 |
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> |
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 l
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>
show more ...
|
| b211a306 | 06-Feb-2026 |
Randy Dunlap <rdunlap@infradead.org> |
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
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>
show more ...
|
| 330367bd | 23-Jan-2026 |
Jonathan Corbet <corbet@lwn.net> |
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/cov
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.
show more ...
|
| 33220c1f | 19-Jan-2026 |
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> |
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>
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>
show more ...
|
| 7ef684c9 | 19-Jan-2026 |
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> |
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.or
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>
show more ...
|
| e68c84b9 | 19-Jan-2026 |
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> |
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.
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>
show more ...
|
| b0b88915 | 19-Jan-2026 |
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> |
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-b
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>
show more ...
|
| 245f1ab2 | 19-Jan-2026 |
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> |
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-o
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>
show more ...
|
| 50206750 | 19-Jan-2026 |
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> |
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-o
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>
show more ...
|
| f40bba94 | 19-Jan-2026 |
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> |
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
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>
show more ...
|
| 8d08c7c6 | 19-Jan-2026 |
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> |
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-of
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>
show more ...
|