From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
To: Jonathan Corbet <corbet@lwn.net>,
Mauro Carvalho Chehab <mchehab@kernel.org>
Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>,
linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org,
Aleksandr Loktionov <aleksandr.loktionov@intel.com>,
Randy Dunlap <rdunlap@infradead.org>,
Shuah Khan <skhan@linuxfoundation.org>
Subject: [PATCH 0/7] More kernel-doc unit tests
Date: Wed, 18 Mar 2026 15:26:04 +0100 [thread overview]
Message-ID: <cover.1773841456.git.mchehab+huawei@kernel.org> (raw)
Hi Jon,
This series comes after
https://lore.kernel.org/linux-doc/20260318104321.53065c27@foz.lan/T/#t
and contains the remaining patches I have ready to be merged.
Its focus is primarly on adding unit tests for some corner
cases. Several of such tests came from Randy, and were already
previously submitted on some old series.
I added a couple of extra tests there to check if tables and code
blocks will be properly producing rst and man content.
Due to such test, I ended discovering one bug, fixed on the last
patch on this series.
On this series, the actual tests are not part of the unit test
source code. Instead, they're loaded from an yaml file that
uses a properly defined schema. One of the tests check if the
file follows such schema.
Now, the end-to-end validation tool also suports specifying
an yaml file:
$ tools/unittests/test_kdoc_parser.py -h
options:
-h, --help show this help message and exit
-v, --verbose
-f, --failfast
-k, --keyword KEYWORD
Regex pattern to filter test methods
-y, --yaml-file, --yaml YAML_FILE
Name of the yaml file to load
That alows an workflow where, before applying a patch series,
one can save either (or both) html and/or man output into an
yaml and test if something changed before/after a patch series:
$ ./tools/docs/kernel-doc --man --rst --yaml all.yaml . 2>err.log
<apply a patch series>
$ tools/unittests/test_kdoc_parser.py -y all.yaml
...
Ran 154975 tests in 237.783s
OK (expected failures=4)
test_kdoc_parser:
...
Ran 154975 tests
In practice, instead of running all of them, one could use
a subset, like checking only the files that are inside
a Documentation file with:
$ ./tools/docs/kernel-doc --man --rst --yaml kdoc.yaml $(git grep kernel-doc:: Documentation|cut -d: -f4|sort|uniq) 2>/dev/null
<apply a patch series>
$ tools/unittests/test_kdoc_parser.py -y kdoc.yaml
Ran 35701 tests in 40.083s
OK (expected failures=4)
test_kdoc_parser:
CToMan:
test_man_test_Documentation_gpu_rfc_i915_small_bar_h_000: OK
test_man_test_Documentation_gpu_rfc_i915_small_bar_h_001: OK
...
test_rst_test_tools_testing_selftests_kselftest_harness_h_036: OK
test_rst_test_tools_testing_selftests_kselftest_harness_h_037: OK
TestSelfValidate:
test_parse_pass: OK
Ran 35701 tests
and/or use this to help adding corner cases to tools/unittests/kdoc-test.yaml.
The test scope that will be written inside the yaml file is limited
by adding one or more of those parameters:
--man
--rst
--kdoc-item
Please notice that the YAML output currently doesn't work for some
broken kernel-doc markups, as it assumes an 1:1 map between symbols
and source code entries. On such cases, it will print a warning like
this one:
Warning: lengths are different. Ignoring drivers/gpu/drm/drm_gpusvm.c
Currently just 1 test over 35702 ones generated from kernel-doc markup
has this issue.
After this series, we have 121 unit tests, all passing:
$ ./tools/unittests/run.py
Ran 121 tests in 0.141s
OK (expected failures=4)
test_cmatch:
TestSearch:
test_search_acquires_multiple: OK
test_search_acquires_nested_paren: OK
test_search_acquires_simple: OK
test_search_must_hold: OK
test_search_must_hold_shared: OK
test_search_no_false_positive: OK
test_search_no_function: OK
test_search_no_macro_remains: OK
TestSubMultipleMacros:
test_acquires_multiple: OK
test_acquires_nested_paren: OK
test_acquires_simple: OK
test_mixed_macros: OK
test_must_hold: OK
test_must_hold_shared: OK
test_no_false_positive: OK
test_no_function: OK
test_no_macro_remains: OK
TestSubSimple:
test_rise_early_greedy: OK
test_rise_multiple_greedy: OK
test_strip_multiple_acquires: OK
test_sub_count_parameter: OK
test_sub_mixed_placeholders: OK
test_sub_multiple_placeholders: OK
test_sub_no_placeholder: OK
test_sub_single_placeholder: OK
test_sub_with_capture: OK
test_sub_zero_placeholder: OK
TestSubWithLocalXforms:
test_functions_with_acquires_and_releases: OK
test_raw_struct_group: OK
test_raw_struct_group_tagged: OK
test_struct_group: OK
test_struct_group_attr: OK
test_struct_group_tagged_with_private: OK
test_struct_kcov: OK
test_vars_stackdepot: OK
test_kdoc_parser:
CToKdocItem:
test_gen_func2: OK
CToMan:
test_man_acpi_os_acquire_lock: OK
test_man_acpi_os_release_lock: OK
test_man_c_stop: OK
test_man_char_array: OK
test_man_char_pointer_var: OK
test_man_const_char_array: OK
test_man_contend_for_bm: OK
test_man_crypto_alg_lookup: OK
test_man_debugfs_enter_cancellation: OK
test_man_debugfs_leave_cancellation: OK
test_man_doc_with_complex_table: OK
test_man_down_read_trylock: OK
test_man_enum_var: OK
test_man_free_stacks: OK
test_man_func1: OK
test_man_func_with_ascii_artwork: OK
test_man_pool_offset: OK
test_man_prepare_report_consumer: OK
test_man_prepare_report_producer: OK
test_man_simple_tables: OK
test_man_spin_lock: OK
test_man_stack_pools: OK
test_man_static_atomic64_t_var: OK
test_man_struct_kcov: OK
test_man_tcp_sigpool_start: OK
test_man_tomoyo_read_lock: OK
test_man_tomoyo_read_unlock: OK
test_man_tx: OK
test_man_undo_report_consumer: OK
test_man_unsigned_long: OK
test_man_unsigned_long_on_init: OK
test_man_unsigned_long_var_on_uppercase: OK
test_man_unsigned_long_with_default: OK
CToRest:
test_rst_acpi_os_acquire_lock: OK
test_rst_acpi_os_release_lock: OK
test_rst_c_stop: OK
test_rst_char_array: OK
test_rst_char_pointer_var: OK
test_rst_const_char_array: OK
test_rst_contend_for_bm: OK
test_rst_crypto_alg_lookup: OK
test_rst_debugfs_enter_cancellation: OK
test_rst_debugfs_leave_cancellation: OK
test_rst_doc_with_complex_table: OK
test_rst_down_read_trylock: OK
test_rst_enum_var: OK
test_rst_free_stacks: OK
test_rst_func_with_ascii_artwork: OK
test_rst_pool_offset: OK
test_rst_prepare_report_consumer: OK
test_rst_prepare_report_producer: OK
test_rst_simple_tables: OK
test_rst_spin_lock: OK
test_rst_stack_pools: OK
test_rst_static_atomic64_t_var: OK
test_rst_struct_kcov: OK
test_rst_tcp_sigpool_start: OK
test_rst_tomoyo_read_lock: OK
test_rst_tomoyo_read_unlock: OK
test_rst_tx: OK
test_rst_undo_report_consumer: OK
test_rst_unsigned_long: OK
test_rst_unsigned_long_on_init: OK
test_rst_unsigned_long_var_on_uppercase: OK
test_rst_unsigned_long_with_default: OK
KdocItemToMan:
test_man_func2: OK
KdocItemToRest:
test_rst_func2: OK
TestSelfValidate:
test_parse_pass: OK
test_kdoc_test_schema:
TestYAMLSchemaValidation:
test_kdoc_test_yaml_followsschema: OK
test_tokenizer:
TestPublicPrivate:
test_balanced_inner_private: OK
test_balanced_non_greddy_private: OK
test_balanced_private: OK
test_no private: OK
test_unbalanced_inner_private: OK
test_unbalanced_private: OK
test_unbalanced_struct_group_tagged_with_private: OK
test_unbalanced_two_struct_group_tagged_first_with_private: OK
test_unbalanced_without_end_of_line: OK
TestTokenizer:
test_basic_tokens: OK
test_depth_counters: OK
test_mismatch_error: OK
Ran 121 tests
The new tests covered by the two series I sent today do an end-to-end
check of the most important logic, as they verify:
- source code parsed into a KdocItem;
- KdocItem to both man and rst;
- source to man and to rst output formats.
The coverage of such tests are:
- c_lex;
- kdoc_item;
- kdoc_output;
- kdoc_parser;
- kdoc_re;
- xforms_lists.
Not 100% of kernel-doc, but the most relevant parts (and the ones
that require more maintainance) are now checked. It doesn't mean
that all possible corner cases are mapped, but it should be able
to identify lots of potential regressions, while still running
on fractions of seconds.
Mauro Carvalho Chehab (7):
docs: kdoc_parser: add some debug for variable parsing
unittests: test_kdoc_parser: add command line arg to read a YAML file
MAINTAINERS: update documentation scripts to add unittests
docs: tools: include kdoc_yaml_file at documentation
docs: kdoc_yaml_file: add a representer to make strings look nicer
docs: kdoc-test.yaml: add more tests
docs: kdoc_output: fix handling of simple tables
Documentation/tools/kdoc_ancillary.rst | 8 +
MAINTAINERS | 3 +-
tools/lib/python/kdoc/kdoc_output.py | 6 +-
tools/lib/python/kdoc/kdoc_parser.py | 11 +
tools/lib/python/kdoc/kdoc_yaml_file.py | 18 +-
tools/unittests/kdoc-test.yaml | 1548 ++++++++++++++++++++++-
tools/unittests/test_kdoc_parser.py | 23 +-
7 files changed, 1605 insertions(+), 12 deletions(-)
--
2.52.0
next reply other threads:[~2026-03-18 14:26 UTC|newest]
Thread overview: 10+ messages / expand[flat|nested] mbox.gz Atom feed top
2026-03-18 14:26 Mauro Carvalho Chehab [this message]
2026-03-18 14:26 ` [PATCH 1/7] docs: kdoc_parser: add some debug for variable parsing Mauro Carvalho Chehab
2026-03-18 14:26 ` [PATCH 2/7] unittests: test_kdoc_parser: add command line arg to read a YAML file Mauro Carvalho Chehab
2026-03-18 14:26 ` [PATCH 3/7] MAINTAINERS: update documentation scripts to add unittests Mauro Carvalho Chehab
2026-03-18 14:26 ` [PATCH 4/7] docs: tools: include kdoc_yaml_file at documentation Mauro Carvalho Chehab
2026-03-18 14:26 ` [PATCH 5/7] docs: kdoc_yaml_file: add a representer to make strings look nicer Mauro Carvalho Chehab
2026-03-18 14:26 ` [PATCH 6/7] docs: kdoc-test.yaml: add more tests Mauro Carvalho Chehab
2026-03-18 14:26 ` [PATCH 7/7] docs: kdoc_output: fix handling of simple tables Mauro Carvalho Chehab
2026-03-25 19:33 ` [PATCH 0/7] More kernel-doc unit tests Jonathan Corbet
2026-03-25 19:40 ` Jonathan Corbet
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=cover.1773841456.git.mchehab+huawei@kernel.org \
--to=mchehab+huawei@kernel.org \
--cc=aleksandr.loktionov@intel.com \
--cc=corbet@lwn.net \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=mchehab@kernel.org \
--cc=rdunlap@infradead.org \
--cc=skhan@linuxfoundation.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox