[PATCH 0/7] More kernel-doc unit tests

[PATCH 0/7] More kernel-doc unit tests

[Mauro Carvalho Chehab]

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

[PATCH 1/7] docs: kdoc_parser: add some debug for variable parsing

[Mauro Carvalho Chehab]

This is a new parser that we're still fine-tuning. Add some
extra debug messages to help addressing issues over there.

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>
---
 tools/lib/python/kdoc/kdoc_parser.py | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/kdoc_parser.py
index a10e64589d76..bbad4a3e4d4d 100644
--- a/tools/lib/python/kdoc/kdoc_parser.py
+++ b/tools/lib/python/kdoc/kdoc_parser.py
@@ -882,11 +882,19 @@ class KernelDoc:
                 declaration_name = r.group(1)
 
             default_val = r.group(2)
+
+            self.config.log.debug("Variable proto parser: %s from '%s'",
+                                  r.groups(), proto)
+
         else:
             r= KernRe(OPTIONAL_VAR_ATTR + r"(?:[\w_\s]*)?\s+(?:\*+)?(?:[\w_]+)\s*[\d\]\[]*\s*(=.*)?")
 
             if r.match(proto):
                 default_val = r.group(1)
+
+        if default_val:
+            self.config.log.debug("default: '%s'", default_val)
+
         if not declaration_name:
            self.emit_msg(ln,f"{proto}: can't parse variable")
            return
@@ -894,6 +902,9 @@ class KernelDoc:
         if default_val:
             default_val = default_val.lstrip("=").strip()
 
+        self.config.log.debug("'%s' variable prototype: '%s', default: %s",
+                              declaration_name, proto, default_val)
+
         self.output_declaration("var", declaration_name,
                                 full_proto=full_proto,
                                 default_val=default_val,
-- 
2.52.0

[PATCH 2/7] unittests: test_kdoc_parser: add command line arg to read a YAML file

[Mauro Carvalho Chehab]

The test_kdoc_parser.py already supports loading dynamic tests
when running unit tests.

Add support to read from a different file. This is useful for:
- regression tests before/afer some changes;
- preparing new unit tests;
- test a different yaml before adding its contents at
  tools/unittests/kdoc-test.yaml.

It should be noticed that passing an argument to a unit test
is not too trivial, as unittest core will load itself the
runner with a separate environment. The best (only?) way to
do it is by setting the system environment. This way, when
the class is called by the unit test loader, it can pick
the var from the environment without relying on a global
variable.

The unittest_helper has already provision for it, so let's
use its support.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 tools/unittests/test_kdoc_parser.py | 23 ++++++++++++++++++++---
 1 file changed, 20 insertions(+), 3 deletions(-)

diff --git a/tools/unittests/test_kdoc_parser.py b/tools/unittests/test_kdoc_parser.py
index 723dd8c7f4f3..f2250ef192ce 100755
--- a/tools/unittests/test_kdoc_parser.py
+++ b/tools/unittests/test_kdoc_parser.py
@@ -30,7 +30,7 @@ from kdoc.kdoc_output import RestFormat, ManFormat
 
 from kdoc.xforms_lists import CTransforms
 
-from unittest_helper import run_unittest
+from unittest_helper import TestUnits
 
 
 #
@@ -38,6 +38,10 @@ from unittest_helper import run_unittest
 #
 TEST_FILE = os.path.join(SRC_DIR, "kdoc-test.yaml")
 
+env = {
+    "yaml_file": TEST_FILE
+}
+
 #
 # Ancillary logic to clean whitespaces
 #
@@ -470,7 +474,9 @@ class KernelDocDynamicTests():
         optional ones.
         """
 
-        with open(TEST_FILE, encoding="utf-8") as fp:
+        test_file = os.environ.get("yaml_file", TEST_FILE)
+
+        with open(test_file, encoding="utf-8") as fp:
             testset = yaml.safe_load(fp)
 
         tests = testset["tests"]
@@ -531,4 +537,15 @@ KernelDocDynamicTests.create_tests()
 # Run all tests
 #
 if __name__ == "__main__":
-    run_unittest(__file__)
+    runner = TestUnits()
+    parser = runner.parse_args()
+    parser.add_argument("-y", "--yaml-file", "--yaml",
+                        help='Name of the yaml file to load')
+
+    args = parser.parse_args()
+
+    if args.yaml_file:
+        env["yaml_file"] = os.path.expanduser(args.yaml_file)
+
+    # Run tests with customized arguments
+    runner.run(__file__, parser=parser, args=args, env=env)
-- 
2.52.0

[PATCH 3/7] MAINTAINERS: update documentation scripts to add unittests

[Mauro Carvalho Chehab]

Ensure that we'll receive e-mails for attempts to touch
tools/unittests.

While here, place entries alphabetically sorted.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 MAINTAINERS | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/MAINTAINERS b/MAINTAINERS
index c05a72245049..f0b106a4dd96 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -7679,8 +7679,9 @@ M:	Mauro Carvalho Chehab <mchehab@kernel.org>
 L:	linux-doc@vger.kernel.org
 S:	Maintained
 F:	Documentation/sphinx/
-F:	tools/lib/python/*
 F:	tools/docs/
+F:	tools/lib/python/*
+F:	tools/unittests/*
 
 DOCUMENTATION/ITALIAN
 M:	Federico Vaga <federico.vaga@vaga.pv.it>
-- 
2.52.0

[PATCH 4/7] docs: tools: include kdoc_yaml_file at documentation

[Mauro Carvalho Chehab]

Add an autodoc entry for the new kdoc_yaml_file module.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/tools/kdoc_ancillary.rst | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/Documentation/tools/kdoc_ancillary.rst b/Documentation/tools/kdoc_ancillary.rst
index 85f3806a431a..249753744d11 100644
--- a/Documentation/tools/kdoc_ancillary.rst
+++ b/Documentation/tools/kdoc_ancillary.rst
@@ -53,3 +53,11 @@ Python version ancillary methods
    :members:
    :show-inheritance:
    :undoc-members:
+
+Write output on YAML file
+=========================
+
+.. automodule:: lib.python.kdoc.kdoc_yaml_file
+   :members:
+   :show-inheritance:
+   :undoc-members:
-- 
2.52.0

[PATCH 5/7] docs: kdoc_yaml_file: add a representer to make strings look nicer

[Mauro Carvalho Chehab]

The strings representation is not ok, currently. Add a helper
function to improve it, and drop blank lines at beginning and
at the end of the dumps

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 tools/lib/python/kdoc/kdoc_yaml_file.py | 18 +++++++++++++++---
 1 file changed, 15 insertions(+), 3 deletions(-)

diff --git a/tools/lib/python/kdoc/kdoc_yaml_file.py b/tools/lib/python/kdoc/kdoc_yaml_file.py
index db131503c3f6..18737abb1176 100644
--- a/tools/lib/python/kdoc/kdoc_yaml_file.py
+++ b/tools/lib/python/kdoc/kdoc_yaml_file.py
@@ -126,7 +126,7 @@ class KDocTestFile():
                 else:
                     key = "rst"
 
-                expected_dict[key]= out_style.output_symbols(fname, [arg])
+                expected_dict[key]= out_style.output_symbols(fname, [arg]).strip()
 
             name = f"{base_name}_{i:03d}"
 
@@ -148,8 +148,20 @@ class KDocTestFile():
         """
         import yaml
 
+        # Helper function to better handle multilines
+        def str_presenter(dumper, data):
+            if "\n" in data:
+                return dumper.represent_scalar("tag:yaml.org,2002:str", data, style="|")
+
+            return dumper.represent_scalar("tag:yaml.org,2002:str", data)
+
+        # Register the representer
+        yaml.add_representer(str, str_presenter)
+
         data = {"tests": self.tests}
 
         with open(self.test_file, "w", encoding="utf-8") as fp:
-            yaml.safe_dump(data, fp, sort_keys=False, default_style="|",
-                           default_flow_style=False, allow_unicode=True)
+            yaml.dump(data, fp,
+                      sort_keys=False, width=120, indent=2,
+                      default_flow_style=False, allow_unicode=True,
+                      explicit_start=False, explicit_end=False)
-- 
2.52.0

[PATCH 6/7] docs: kdoc-test.yaml: add more tests

[Mauro Carvalho Chehab]

Add extra tests to check if the new "var" type is properly
handled and to cover mutex context annotations.

Co-developed-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 tools/unittests/kdoc-test.yaml | 1548 +++++++++++++++++++++++++++++++-
 1 file changed, 1546 insertions(+), 2 deletions(-)

diff --git a/tools/unittests/kdoc-test.yaml b/tools/unittests/kdoc-test.yaml
index b6e04f10ccdb..14d36daa1bba 100644
--- a/tools/unittests/kdoc-test.yaml
+++ b/tools/unittests/kdoc-test.yaml
@@ -22,7 +22,6 @@ tests:
       */
     int func1(char *arg1) { return 0; };
 
-
   expected:
   - rst: |
     .. c:function:: int func1 (char *arg1)
@@ -134,7 +133,6 @@ tests:
 
         always return 0.
 
-    # TODO: how to handle timestamps at .TH?
     man: |
       .TH "func2" 9 "February 2026"  "" "Kernel API Manual"
       .SH NAME
@@ -152,3 +150,1549 @@ tests:
       .SH "SEE ALSO"
       .PP
       Kernel file \fBfunc2.c\fR
+
+- name: doc_with_complex_table
+  description: Test if complex tables are handled
+  fname: mock.c
+  source: |
+    /**
+      * DOC: Supported input formats and encodings
+      *
+      * Depending on the Hardware configuration of the Controller IP, it supports
+      * a subset of the following input formats and encodings on its internal
+      * 48bit bus.
+      *
+      * +----------------------+----------------------------------+------------------------------+
+      * | Format Name          | Format Code                      | Encodings                    |
+      * +======================+==================================+==============================+
+      * | RGB 4:4:4 8bit       | ``MEDIA_BUS_FMT_RGB888_1X24``    | ``V4L2_YCBCR_ENC_DEFAULT``   |
+      * +----------------------+----------------------------------+------------------------------+
+      * | RGB 4:4:4 10bits     | ``MEDIA_BUS_FMT_RGB101010_1X30`` | ``V4L2_YCBCR_ENC_DEFAULT``   |
+      * +----------------------+----------------------------------+------------------------------+
+      */
+  expected:
+    - man: |
+        .TH "Supported input formats and encodings" 9 "March 2026" "" "Kernel API Manual"
+        .SH "Supported input formats and encodings"
+        Depending on the Hardware configuration of the Controller IP, it supports
+        a subset of the following input formats and encodings on its internal
+        48bit bus.
+        .PP
+
+
+        .TS
+        box;
+        l	l	l.
+        \fBFormat Name\fP	\fBFormat Code\fP	\fBEncodings\fP
+        _
+        RGB 4:4:4 8bit	``MEDIA_BUS_FMT_RGB888_1X24	V4L2_YCBCR_ENC_DEFAULT
+        RGB 4:4:4 10bits	MEDIA_BUS_FMT_RGB101010_1X30	V4L2_YCBCR_ENC_DEFAULT``
+        .TE
+        .SH "SEE ALSO"
+        .PP
+        Kernel file \fBmock.c\fR
+
+      rst: |-
+        .. _Supported input formats and encodings:
+        **Supported input formats and encodings**
+        Depending on the Hardware configuration of the Controller IP, it supports
+        a subset of the following input formats and encodings on its internal
+        48bit bus.
+        +----------------------+----------------------------------+------------------------------+
+        | Format Name          | Format Code                      | Encodings                    |
+        +======================+==================================+==============================+
+        | RGB 4:4:4 8bit       | ``MEDIA_BUS_FMT_RGB888_1X24``    | ``V4L2_YCBCR_ENC_DEFAULT``   |
+        +----------------------+----------------------------------+------------------------------+
+        | RGB 4:4:4 10bits     | ``MEDIA_BUS_FMT_RGB101010_1X30`` | ``V4L2_YCBCR_ENC_DEFAULT``   |
+        +----------------------+----------------------------------+------------------------------+
+- name: func_with_ascii_artwork
+  description: Test if ascii artwork is properly output
+  fname: mock.c
+  source: |
+    /**
+      * add_cxl_resources() - reflect CXL fixed memory windows in iomem_resource
+      * @cxl_res: A standalone resource tree where each CXL window is a sibling
+      *
+      * Walk each CXL window in @cxl_res and add it to iomem_resource potentially
+      * expanding its boundaries to ensure that any conflicting resources become
+      * children. If a window is expanded it may then conflict with a another window
+      * entry and require the window to be truncated or trimmed. Consider this
+      * situation::
+      *
+      *      |-- "CXL Window 0" --||----- "CXL Window 1" -----|
+      *      |--------------- "System RAM" -------------|
+      *
+      * ...where platform firmware has established as System RAM resource across 2
+      * windows, but has left some portion of window 1 for dynamic CXL region
+      * provisioning. In this case "Window 0" will span the entirety of the "System
+      * RAM" span, and "CXL Window 1" is truncated to the remaining tail past the end
+      * of that "System RAM" resource.
+      */
+    static int add_cxl_resources(struct resource *cxl_res);
+  expected:
+    - man: |-
+        .TH "add_cxl_resources" 9 "March 2026" "" "Kernel API Manual"
+        .SH NAME
+        add_cxl_resources \- reflect CXL fixed memory windows in iomem_resource
+        .SH SYNOPSIS
+        .B "int" add_cxl_resources
+        .BI "(struct resource *cxl_res "  ");"
+        .SH ARGUMENTS
+        .IP "cxl_res" 12
+        A standalone resource tree where each CXL window is a sibling
+        .SH "DESCRIPTION"
+        Walk each CXL window in \fIcxl_res\fP and add it to iomem_resource potentially
+        expanding its boundaries to ensure that any conflicting resources become
+        children. If a window is expanded it may then conflict with a another window
+        entry and require the window to be truncated or trimmed. Consider this
+        situation:
+        .nf
+
+             |-- "CXL Window 0" --||----- "CXL Window 1" -----|
+             |--------------- "System RAM" -------------|
+
+
+        .fi
+        .PP
+
+        \&...where platform firmware has established as System RAM resource across 2
+        windows, but has left some portion of window 1 for dynamic CXL region
+        provisioning. In this case "Window 0" will span the entirety of the "System
+        RAM" span, and "CXL Window 1" is truncated to the remaining tail past the end
+        of that "System RAM" resource.
+        .SH "SEE ALSO"
+        .PP
+        Kernel file \fBmock.c\fR
+      rst: |
+        .. c:function:: int add_cxl_resources (struct resource *cxl_res)
+
+          reflect CXL fixed memory windows in iomem_resource
+
+        .. container:: kernelindent
+
+          **Parameters**
+
+          ``struct resource *cxl_res``
+            A standalone resource tree where each CXL window is a sibling
+
+          **Description**
+
+          Walk each CXL window in **cxl_res** and add it to iomem_resource potentially
+          expanding its boundaries to ensure that any conflicting resources become
+          children. If a window is expanded it may then conflict with a another window
+          entry and require the window to be truncated or trimmed. Consider this
+          situation::
+
+            |-- "CXL Window 0" --||----- "CXL Window 1" -----|
+            |--------------- "System RAM" -------------|
+
+          ...where platform firmware has established as System RAM resource across 2
+          windows, but has left some portion of window 1 for dynamic CXL region
+          provisioning. In this case "Window 0" will span the entirety of the "System
+          RAM" span, and "CXL Window 1" is truncated to the remaining tail past the end
+          of that "System RAM" resource.
+
+- name: simple_tables
+  description: Test formatting two simple tables
+  fname: mock.c
+  source: |
+    /**
+     * bitmap_onto - translate one bitmap relative to another
+     *      @dst: resulting translated bitmap
+     *      @orig: original untranslated bitmap
+     *      @relmap: bitmap relative to which translated
+     *      @bits: number of bits in each of these bitmaps
+     *
+     *      =============== ============== =================
+     *      @orig           tmp            @dst
+     *      0                0             40
+     *      1                1             41
+     *      =============== ============== =================
+     *
+     * And:
+     *
+     *      =============== ============== =================
+     *      @orig           tmp            @dst
+     *      =============== ============== =================
+     *      9                9             95
+     *      10               0             40 [#f1]_
+     *      =============== ============== =================
+     */
+    void bitmap_onto(unsigned long *dst, const unsigned long *orig,
+                     const unsigned long *relmap, unsigned int bits);
+  expected:
+    - man: |
+        .TH "bitmap_onto" 9 "March 2026" "" "Kernel API Manual"
+        .SH NAME
+        bitmap_onto \- translate one bitmap relative to another
+        .SH SYNOPSIS
+        .B "void" bitmap_onto
+        .BI "(unsigned long *dst "  ","
+        .BI "const unsigned long *orig "  ","
+        .BI "const unsigned long *relmap "  ","
+        .BI "unsigned int bits "  ");"
+        .SH ARGUMENTS
+        .IP "dst" 12
+        resulting translated bitmap
+        .IP "orig" 12
+        original untranslated bitmap
+        .IP "relmap" 12
+        bitmap relative to which translated
+        .IP "bits" 12
+        number of bits in each of these bitmaps
+        .SH "DESCRIPTION"
+
+        .TS
+        box;
+        l	l	l.
+        \fIorig\fP	tmp	\fIdst\fP
+        0	0	40
+        1	1	41
+        .TE
+        .PP
+
+        And:
+        .PP
+
+
+        .TS
+        box;
+        l	l	l.
+        \fIorig\fP	tmp	\fIdst\fP
+        .TE
+        9                9             95
+        10               0             40 [#f1]_
+        .SH "SEE ALSO"
+        .PP
+        Kernel file \fBmock.c\fR
+
+      rst: |
+        .. c:function:: void bitmap_onto (unsigned long *dst, const unsigned long *orig, const unsigned long *relmap,  unsigned int bits)
+
+          translate one bitmap relative to another
+
+        .. container:: kernelindent
+
+          **Parameters**
+
+          ``unsigned long *dst``
+            resulting translated bitmap
+
+          ``const unsigned long *orig``
+            original untranslated bitmap
+
+          ``const unsigned long *relmap``
+            bitmap relative to which translated
+
+          ``unsigned int bits``
+            number of bits in each of these bitmaps
+
+          **Description**
+
+              =============== ============== =================
+              **orig**           tmp            **dst**
+              0                0             40
+              1                1             41
+              =============== ============== =================
+
+          And:
+
+              =============== ============== =================
+              **orig**           tmp            **dst**
+              =============== ============== =================
+              9                9             95
+              10               0             40 [#f1]_
+              =============== ============== =================
+
+#
+# Variable tests from Randy Dunlap's testset
+#
+- name: unsigned_long_var_on_uppercase
+  description: Test an unsigned long varaible in uppercase
+  fname: mock-vars.c
+  source: |
+    /**
+     * var ROOT_DEV - system root device
+     *
+     * @ROOT_DEV is either the successful root device or the root device
+     * that failed boot in the boot failure message.
+     */
+    unsigned long ROOT_DEV;
+  expected:
+  - man: |
+      .TH "var ROOT_DEV" 9 "February 2026"  "" "Kernel API Manual"
+      .SH NAME
+      ROOT_DEV \- system root device
+      .SH SYNOPSIS
+      unsigned long ROOT_DEV;
+      .SH "Description"
+      \fIROOT_DEV\fP is either the successful root device or the root device
+      that failed boot in the boot failure message.
+      .SH "SEE ALSO"
+      .PP
+      Kernel file \fBmock-vars.c\fR
+    rst: |
+      .. c:macro:: ROOT_DEV
+
+        ``unsigned long ROOT_DEV;``
+
+        system root device
+
+        **Description**
+
+        **ROOT_DEV** is either the successful root device or the root device
+        that failed boot in the boot failure message.
+- name: enum_var
+  description: Test an enum var with __read_mostly
+  fname: mock-vars.c
+  source: |
+    /**
+     * var system_state - system state used during boot or suspend/hibernate/resume
+     *
+     * @system_state can be used during boot to determine if it is safe to
+     * make certain calls to other parts of the kernel. It can also be used
+     * during suspend/hibernate or resume to determine the order of actions
+     * that need to be executed. The numerical values of system_state are
+     * sometimes used in numerical ordering tests, so the relative values
+     * must not be altered.
+     */
+    enum system_states system_state __read_mostly;
+  expected:
+  - man: |
+      .TH "var system_state" 9 "February 2026"  "" "Kernel API Manual"
+      .SH NAME
+      system_state \- system state used during boot or suspend/hibernate/resume
+      .SH SYNOPSIS
+      enum system_states system_state __read_mostly;
+      .SH "Description"
+      \fIsystem_state\fP can be used during boot to determine if it is safe to
+      make certain calls to other parts of the kernel. It can also be used
+      during suspend/hibernate or resume to determine the order of actions
+      that need to be executed. The numerical values of system_state are
+      sometimes used in numerical ordering tests, so the relative values
+      must not be altered.
+      .SH "SEE ALSO"
+      .PP
+      Kernel file \fBmock-vars.c\fR
+    rst: |
+      .. c:macro:: system_state
+
+        ``enum system_states system_state __read_mostly;``
+
+        system state used during boot or suspend/hibernate/resume
+
+        **Description**
+
+        **system_state** can be used during boot to determine if it is safe to
+        make certain calls to other parts of the kernel. It can also be used
+        during suspend/hibernate or resume to determine the order of actions
+        that need to be executed. The numerical values of system_state are
+        sometimes used in numerical ordering tests, so the relative values
+        must not be altered.
+- name: char_pointer_var
+  description: Test char * var with __ro_after_init
+  fname: mock-vars.c
+  source: |
+    /**
+     * var saved_command_line - kernel's command line, saved from use at
+     * any later time in the kernel.
+     */
+    char *saved_command_line __ro_after_init;
+  expected:
+  - man: |
+      .TH "var saved_command_line" 9 "February 2026"  "" "Kernel API Manual"
+      .SH NAME
+      saved_command_line \- kernel's command line, saved from use at any later time in the kernel.
+      .SH SYNOPSIS
+      char *saved_command_line __ro_after_init;
+      .SH "SEE ALSO"
+      .PP
+      Kernel file \fBmock-vars.c\fR
+    rst: |
+      .. c:macro:: saved_command_line
+
+        ``char *saved_command_line __ro_after_init;``
+
+        kernel's command line, saved from use at any later time in the kernel.
+- name: unsigned_long_with_default
+  description: Test an unsigned long var that is set to a default value
+  fname: mock-vars.c
+  source: |
+    /**
+     * var loop_per_jiffy - calculated loop count needed to consume one jiffy
+     * of time
+     */
+    unsigned long loops_per_jiffy = (1<<12);
+  expected:
+  - man: |
+      .TH "var loops_per_jiffy" 9 "February 2026"  "" "Kernel API Manual"
+      .SH NAME
+      loops_per_jiffy \- calculated loop count needed to consume one jiffy of time
+      .SH SYNOPSIS
+      unsigned long loops_per_jiffy = (1<<12);
+      .SH "Initialization"
+      default: (1<<12)
+      .SH "SEE ALSO"
+      .PP
+      Kernel file \fBmock-vars.c\fR
+    rst: |
+      .. c:macro:: loops_per_jiffy
+
+        ``unsigned long loops_per_jiffy = (1<<12);``
+
+        calculated loop count needed to consume one jiffy of time
+
+        **Initialization**
+
+        default: ``(1<<12)``
+- name: unsigned_long
+  description: test a simple unsigned long variable.
+  fname: mock-vars.c
+  source: |
+    /**
+     * var preset_lpj - lpj (loops per jiffy) value set from kernel
+     * command line using "lpj=VALUE"
+     *
+     * See Documentation/admin-guide/kernel-parameters.txt ("lpj=") for details.
+     */
+    unsigned long preset_lpj;
+  expected:
+  - man: |
+      .TH "var preset_lpj" 9 "February 2026"  "" "Kernel API Manual"
+      .SH NAME
+      preset_lpj \- lpj (loops per jiffy) value set from kernel command line using "lpj=VALUE"
+      .SH SYNOPSIS
+      unsigned long preset_lpj;
+      .SH "Description"
+      See Documentation/admin-guide/kernel-parameters.txt ("lpj=") for details.
+      .SH "SEE ALSO"
+      .PP
+      Kernel file \fBmock-vars.c\fR
+    rst: |
+      .. c:macro:: preset_lpj
+
+        ``unsigned long preset_lpj;``
+
+        lpj (loops per jiffy) value set from kernel command line using "lpj=VALUE"
+
+        **Description**
+
+        See Documentation/admin-guide/kernel-parameters.txt ("lpj=") for details.
+- name: char_array
+  description: test a char array variable
+  fname: mock-vars.c
+  source: |
+    /**
+     * var linux_proc_banner - text used from /proc/version file
+     *
+     * * first %s is sysname (e.g., "Linux")
+     * * second %s is release
+     * * third %s is version
+     */
+    char linux_proc_banner[];
+  expected:
+  - man: |
+      .TH "var linux_proc_banner" 9 "February 2026"  "" "Kernel API Manual"
+      .SH NAME
+      linux_proc_banner \- text used from /proc/version file
+      .SH SYNOPSIS
+      char linux_proc_banner[];
+      .SH "Description"
+      .IP \[bu]
+      first s is sysname (e.g., "Linux")
+      .IP \[bu]
+      second s is release
+      .IP \[bu]
+      third s is version
+      .SH "SEE ALSO"
+      .PP
+      Kernel file \fBmock-vars.c\fR
+    rst: |
+      .. c:macro:: linux_proc_banner
+
+        ``char linux_proc_banner[];``
+
+        text used from /proc/version file
+
+        **Description**
+
+        * first ``s`` is sysname (e.g., "Linux")
+        * second ``s`` is release
+        * third ``s`` is version
+- name: const_char_array
+  description: test a const char array variable
+  fname: mock-vars.c
+  source: |
+    /**
+     * var linux_banner - Linux boot banner, usually printed at boot time
+     */
+    const char linux_banner[];
+  expected:
+  - man: |
+      .TH "var linux_banner" 9 "February 2026"  "" "Kernel API Manual"
+      .SH NAME
+      linux_banner \- Linux boot banner, usually printed at boot time
+      .SH SYNOPSIS
+      const char linux_banner[];
+      .SH "SEE ALSO"
+      .PP
+      Kernel file \fBmock-vars.c\fR
+    rst: |
+      .. c:macro:: linux_banner
+
+        ``const char linux_banner[];``
+
+        Linux boot banner, usually printed at boot time
+- name: static_atomic64_t_var
+  description: test a static atomi64_t variable
+  fname: mock-vars.c
+  source: |
+    /**
+     * var diskseq - unique sequence number for block device instances
+     *
+     * Allows userspace to associate uevents to the lifetime of a device
+     */
+    static atomic64_t diskseq;
+  expected:
+  - man: |
+      .TH "var diskseq" 9 "February 2026"  "" "Kernel API Manual"
+      .SH NAME
+      diskseq \- unique sequence number for block device instances
+      .SH SYNOPSIS
+      static atomic64_t diskseq;
+      .SH "Description"
+      Allows userspace to associate uevents to the lifetime of a device
+      .SH "SEE ALSO"
+      .PP
+      Kernel file \fBmock-vars.c\fR
+    rst: |
+      .. c:macro:: diskseq
+
+        ``static atomic64_t diskseq;``
+
+        unique sequence number for block device instances
+
+        **Description**
+
+        Allows userspace to associate uevents to the lifetime of a device
+- name: unsigned_long_on_init
+  description: test an unsigned long var at "init" with a different timestamp.
+  fname: init/mock-vars.c
+  source: |
+    /**
+     * var rtnl_mutex - historical global lock for networking control operations.
+     *
+     * @rtnl_mutex is used to serialize rtnetlink requests
+     * and protect all kernel internal data structures related to networking.
+     *
+     * See Documentation/networking/netdevices.rst for details.
+     * Often known as the rtnl_lock, although rtnl_lock is a kernel function.
+     */
+    unsigned long rtnl_mutex;
+  expected:
+  - man: |
+      .TH "var rtnl_mutex" 9 "February 2026"  "init" "Kernel API Manual"
+      .SH NAME
+      rtnl_mutex \- historical global lock for networking control operations.
+      .SH SYNOPSIS
+      unsigned long rtnl_mutex;
+      .SH "Description"
+      \fIrtnl_mutex\fP is used to serialize rtnetlink requests
+      and protect all kernel internal data structures related to networking.
+      .PP
+
+      See Documentation/networking/netdevices.rst for details.
+      Often known as the rtnl_lock, although rtnl_lock is a kernel function.
+      .SH "SEE ALSO"
+      .PP
+      Kernel file \fBinit/mock-vars.c\fR
+    rst: |
+      .. c:macro:: rtnl_mutex
+
+        ``unsigned long rtnl_mutex;``
+
+      historical global lock for networking control operations.
+
+      **Description**
+
+      **rtnl_mutex** is used to serialize rtnetlink requests
+      and protect all kernel internal data structures related to networking.
+
+      See Documentation/networking/netdevices.rst for details.
+      Often known as the rtnl_lock, although rtnl_lock is a kernel function.
+
+
+- name: struct_kcov
+  fname: mock_tests/kdoc-drop-ctx-lock.c
+  source: |
+    /**
+     * struct kcov - kcov descriptor (one per opened debugfs file).
+     * State transitions of the descriptor:
+     *
+     *  - initial state after open()
+     *  - then there must be a single ioctl(KCOV_INIT_TRACE) call
+     *  - then, mmap() call (several calls are allowed but not useful)
+     *  - then, ioctl(KCOV_ENABLE, arg), where arg is
+     *      KCOV_TRACE_PC - to trace only the PCs
+     *      or
+     *      KCOV_TRACE_CMP - to trace only the comparison operands
+     *  - then, ioctl(KCOV_DISABLE) to disable the task.
+     *
+     * Enabling/disabling ioctls can be repeated (only one task a time allowed).
+     */
+    struct kcov {
+            /**
+             * @refcount: Reference counter. We keep one for:
+             *  - opened file descriptor
+             *  - task with enabled coverage (we can't unwire it from another task)
+             *  - each code section for remote coverage collection
+             */
+            refcount_t              refcount;
+            /**
+             * @lock: The lock protects mode, size, area and t.
+             */
+            spinlock_t              lock;
+            /**
+             * @mode: the kcov_mode
+             */
+            enum kcov_mode          mode __guarded_by(&lock);
+            /**
+             * @size: Size of arena (in long's).
+             */
+            unsigned int            size __guarded_by(&lock);
+            /**
+             * @area: Coverage buffer shared with user space.
+             */
+            void                    *area __guarded_by(&lock);
+            /**
+             * @t: Task for which we collect coverage, or NULL.
+             */
+            struct task_struct      *t __guarded_by(&lock);
+            /**
+             * @remote: Collecting coverage from remote (background) threads.
+             */
+            bool                    remote;
+            /**
+             * @remote_size: Size of remote area (in long's).
+             */
+            unsigned int            remote_size;
+            /**
+             * @sequence: Sequence is incremented each time kcov is reenabled,
+             * used by kcov_remote_stop(), see the comment there.
+             */
+            int                     sequence;
+    };
+  expected:
+  - man: |
+      .TH "struct kcov" 9 "February 2026"  "mock_tests" "Kernel API Manual"
+      .SH NAME
+      struct kcov \- kcov descriptor (one per opened debugfs file). State transitions of the descriptor:
+      .SH SYNOPSIS
+      struct kcov {
+      .br
+      .BI "    refcount_t refcount;"
+      .br
+      .BI "    spinlock_t lock;"
+      .br
+      .BI "    enum kcov_mode          mode;"
+      .br
+      .BI "    unsigned int            size;"
+      .br
+      .BI "    void *area;"
+      .br
+      .BI "    struct task_struct      *t;"
+      .br
+      .BI "    bool remote;"
+      .br
+      .BI "    unsigned int            remote_size;"
+      .br
+      .BI "    int sequence;"
+      .br
+      .BI "
+      };
+      .br
+
+      .SH Members
+      .IP "refcount" 12
+      Reference counter. We keep one for:
+      .IP \[bu]
+      opened file descriptor
+      .IP \[bu]
+      task with enabled coverage (we can't unwire it from another task)
+      .IP \[bu]
+      each code section for remote coverage collection
+      .IP "lock" 12
+      The lock protects mode, size, area and t.
+      .IP "mode" 12
+      the kcov_mode
+      .IP "size" 12
+      Size of arena (in long's).
+      .IP "area" 12
+      Coverage buffer shared with user space.
+      .IP "t" 12
+      Task for which we collect coverage, or NULL.
+      .IP "remote" 12
+      Collecting coverage from remote (background) threads.
+      .IP "remote_size" 12
+      Size of remote area (in long's).
+      .IP "sequence" 12
+      Sequence is incremented each time kcov is reenabled,
+      used by \fBkcov_remote_stop\fP, see the comment there.
+      .SH "Description"
+      .IP \[bu]
+      initial state after \fBopen\fP
+      .IP \[bu]
+      then there must be a single ioctl(KCOV_INIT_TRACE) call
+      .IP \[bu]
+      then, \fBmmap\fP call (several calls are allowed but not useful)
+      .IP \[bu]
+      then, ioctl(KCOV_ENABLE, arg), where arg is
+      KCOV_TRACE_PC - to trace only the PCs
+      or
+      KCOV_TRACE_CMP - to trace only the comparison operands
+      .IP \[bu]
+      then, ioctl(KCOV_DISABLE) to disable the task.
+      .PP
+
+      Enabling/disabling ioctls can be repeated (only one task a time allowed).
+      .SH "SEE ALSO"
+      .PP
+      Kernel file \fBmock_tests/kdoc-drop-ctx-lock.c\fR
+    rst: |
+      .. c:struct:: kcov
+
+        kcov descriptor (one per opened debugfs file). State transitions of the descriptor:
+
+      .. container:: kernelindent
+
+        **Definition**::
+
+          struct kcov {
+              refcount_t refcount;
+              spinlock_t lock;
+              enum kcov_mode          mode;
+              unsigned int            size;
+              void *area;
+              struct task_struct      *t;
+              bool remote;
+              unsigned int            remote_size;
+              int sequence;
+          };
+
+        **Members**
+
+        ``refcount``
+          Reference counter. We keep one for:
+           - opened file descriptor
+           - task with enabled coverage (we can't unwire it from another task)
+           - each code section for remote coverage collection
+
+        ``lock``
+          The lock protects mode, size, area and t.
+
+        ``mode``
+          the kcov_mode
+
+        ``size``
+          Size of arena (in long's).
+
+        ``area``
+          Coverage buffer shared with user space.
+
+        ``t``
+          Task for which we collect coverage, or NULL.
+
+        ``remote``
+          Collecting coverage from remote (background) threads.
+
+        ``remote_size``
+          Size of remote area (in long's).
+
+        ``sequence``
+          Sequence is incremented each time kcov is reenabled,
+          used by kcov_remote_stop(), see the comment there.
+
+
+       **Description**
+
+       - initial state after open()
+       - then there must be a single ioctl(KCOV_INIT_TRACE) call
+       - then, mmap() call (several calls are allowed but not useful)
+       - then, ioctl(KCOV_ENABLE, arg), where arg is
+           KCOV_TRACE_PC - to trace only the PCs
+           or
+           KCOV_TRACE_CMP - to trace only the comparison operands
+       - then, ioctl(KCOV_DISABLE) to disable the task.
+
+       Enabling/disabling ioctls can be repeated (only one task a time allowed).
+
+- name: pool_offset
+  description: mock_tests/kdoc-drop-ctx-lock.c line 83
+  fname: mock_tests/kdoc-drop-ctx-lock.c
+  source: |
+    /**
+     * var pool_offset - Offset to the unused space in the currently used pool.
+     *
+     */
+    size_t pool_offset __guarded_by(&pool_lock) = DEPOT_POOL_SIZE;
+  expected:
+  - man: |
+      .TH "var pool_offset" 9 "February 2026"  "mock_tests" "Kernel API Manual"
+      .SH NAME
+      pool_offset \- Offset to the unused space in the currently used pool.
+      .SH SYNOPSIS
+      size_t pool_offset __guarded_by(&pool_lock) = DEPOT_POOL_SIZE;
+      .SH "Initialization"
+      default: DEPOT_POOL_SIZE
+      .SH "SEE ALSO"
+      .PP
+      Kernel file \fBmock_tests/kdoc-drop-ctx-lock.c\fR
+    rst: |
+      .. c:macro:: pool_offset
+
+        ``size_t pool_offset __guarded_by(&pool_lock) = DEPOT_POOL_SIZE;``
+
+        Offset to the unused space in the currently used pool.
+
+        **Initialization**
+
+        default: ``DEPOT_POOL_SIZE``
+- name: free_stacks
+  description: mock_tests/kdoc-drop-ctx-lock.c line 88
+  fname: mock_tests/kdoc-drop-ctx-lock.c
+  source: |
+    /**
+     * var free_stacks - Freelist of stack records within stack_pools.
+     *
+     */
+    __guarded_by(&pool_lock) LIST_HEAD(free_stacks);
+  expected:
+  - man: |
+      .TH "var free_stacks" 9 "February 2026"  "mock_tests" "Kernel API Manual"
+      .SH NAME
+      free_stacks \- Freelist of stack records within stack_pools.
+      .SH SYNOPSIS
+      __guarded_by(&pool_lock) LIST_HEAD(free_stacks);
+      .SH "SEE ALSO"
+      .PP
+      Kernel file \fBmock_tests/kdoc-drop-ctx-lock.c\fR
+    rst: |
+      .. c:macro:: free_stacks
+
+        ``__guarded_by(&pool_lock) LIST_HEAD(free_stacks);``
+
+        Freelist of stack records within stack_pools.
+- name: stack_pools
+  description: mock_tests/kdoc-drop-ctx-lock.c line 94
+  fname: mock_tests/kdoc-drop-ctx-lock.c
+  source: |
+    /**
+     * var stack_pools - Array of memory regions that store stack records.
+     *
+     */
+    void **stack_pools __pt_guarded_by(&pool_lock);
+  expected:
+  - man: |
+      .TH "var stack_pools" 9 "February 2026"  "mock_tests" "Kernel API Manual"
+      .SH NAME
+      stack_pools \- Array of memory regions that store stack records.
+      .SH SYNOPSIS
+      void **stack_pools __pt_guarded_by(&pool_lock);
+      .SH "SEE ALSO"
+      .PP
+      Kernel file \fBmock_tests/kdoc-drop-ctx-lock.c\fR
+    rst: |
+      .. c:macro:: stack_pools
+
+        ``void **stack_pools __pt_guarded_by(&pool_lock);``
+
+        Array of memory regions that store stack records.
+- name: prepare_report_consumer
+  description: mock_tests/kdoc-drop-ctx-lock.c line 103
+  fname: mock_tests/kdoc-drop-ctx-lock.c
+  source: |
+    /**
+     * prepare_report_consumer - prepare the report consumer
+     * @flags: flags
+     * @ai: not that AI
+     * @other_info: yes that
+     */
+    bool prepare_report_consumer(unsigned long *flags,
+                                const struct access_info *ai,
+                                struct other_info *other_info)
+            __cond_acquires(true, &report_lock)
+    {
+  expected:
+  - man: |
+      .TH "prepare_report_consumer" 9 "February 2026"  "mock_tests" "Kernel API Manual"
+      .SH NAME
+      prepare_report_consumer \- prepare the report consumer
+      .SH SYNOPSIS
+      .B "bool" prepare_report_consumer
+      .BI "(unsigned long *flags "  ","
+      .BI "const struct access_info *ai "  ","
+      .BI "struct other_info *other_info "  ");"
+      .SH ARGUMENTS
+      .IP "flags" 12
+      flags
+      .IP "ai" 12
+      not that AI
+      .IP "other_info" 12
+      yes that
+      .SH "SEE ALSO"
+      .PP
+      Kernel file \fBmock_tests/kdoc-drop-ctx-lock.c\fR
+    rst: |
+      .. c:function:: bool prepare_report_consumer (unsigned long *flags, const struct access_info *ai, struct other_info *other_info)
+
+         prepare the report consumer
+
+      .. container:: kernelindent
+
+        **Parameters**
+
+        ``unsigned long *flags``
+          flags
+
+        ``const struct access_info *ai``
+          not that AI
+
+        ``struct other_info *other_info``
+          yes that
+- name: tcp_sigpool_start
+  description: mock_tests/kdoc-drop-ctx-lock.c line 117
+  fname: mock_tests/kdoc-drop-ctx-lock.c
+  source: |
+    /**
+     * tcp_sigpool_start - start a tcp message of @id, using @c
+     * @id: TCP message ID
+     * @c: the &tcp_sigpool to use
+     */
+    int tcp_sigpool_start(unsigned int id, struct tcp_sigpool *c) __cond_acquires(0, RCU_BH)
+    {
+  expected:
+  - man: |
+      .TH "tcp_sigpool_start" 9 "February 2026"  "mock_tests" "Kernel API Manual"
+      .SH NAME
+      tcp_sigpool_start \- start a tcp message of @id, using @c
+      .SH SYNOPSIS
+      .B "int" tcp_sigpool_start
+      .BI "(unsigned int id "  ","
+      .BI "struct tcp_sigpool *c "  ");"
+      .SH ARGUMENTS
+      .IP "id" 12
+      TCP message ID
+      .IP "c" 12
+      the \fItcp_sigpool\fP to use
+      .SH "SEE ALSO"
+      .PP
+      Kernel file \fBmock_tests/kdoc-drop-ctx-lock.c\fR
+    rst: |
+      .. c:function:: int tcp_sigpool_start (unsigned int id, struct tcp_sigpool *c)
+
+         start a tcp message of **id**, using **c**
+
+      .. container:: kernelindent
+
+        **Parameters**
+
+        ``unsigned int id``
+          TCP message ID
+
+        ``struct tcp_sigpool *c``
+          the :c:type:`tcp_sigpool` to use
+- name: undo_report_consumer
+  description: mock_tests/kdoc-drop-ctx-lock.c line 129
+  fname: mock_tests/kdoc-drop-ctx-lock.c
+  source: |
+    /**
+     * undo_report_consumer -  teardown a report consumer
+     * @flags: those flags
+     * @ai: not that AI
+     * @other_info: yes that
+     */
+    bool undo_report_consumer(unsigned long *flags,
+                                const struct access_info *ai,
+                                struct other_info *other_info)
+            __cond_releases(true, &report_lock)
+    {
+  expected:
+  - man: |
+      .TH "undo_report_consumer" 9 "February 2026"  "mock_tests" "Kernel API Manual"
+      .SH NAME
+      undo_report_consumer \- teardown a report consumer
+      .SH SYNOPSIS
+      .B "bool" undo_report_consumer
+      .BI "(unsigned long *flags "  ","
+      .BI "const struct access_info *ai "  ","
+      .BI "struct other_info *other_info "  ");"
+      .SH ARGUMENTS
+      .IP "flags" 12
+      those flags
+      .IP "ai" 12
+      not that AI
+      .IP "other_info" 12
+      yes that
+      .SH "SEE ALSO"
+      .PP
+      Kernel file \fBmock_tests/kdoc-drop-ctx-lock.c\fR
+    rst: |
+      .. c:function:: bool undo_report_consumer (unsigned long *flags, const struct access_info *ai, struct other_info *other_info)
+
+         teardown a report consumer
+
+      .. container:: kernelindent
+
+        **Parameters**
+
+        ``unsigned long *flags``
+          those flags
+
+        ``const struct access_info *ai``
+          not that AI
+
+        ``struct other_info *other_info``
+          yes that
+- name: debugfs_enter_cancellation
+  description: mock_tests/kdoc-drop-ctx-lock.c line 143
+  fname: mock_tests/kdoc-drop-ctx-lock.c
+  source: |
+    /**
+     * debugfs_enter_cancellation - begin a cancellation operation on @file
+     * @file: the target file
+     * @cancellation: the operation to execute
+     */
+    void debugfs_enter_cancellation(struct file *file,
+                                    struct debugfs_cancellation *cancellation) __acquires(cancellation)
+    { }
+  expected:
+  - man: |
+      .TH "debugfs_enter_cancellation" 9 "February 2026"  "mock_tests" "Kernel API Manual"
+      .SH NAME
+      debugfs_enter_cancellation \- begin a cancellation operation on @file
+      .SH SYNOPSIS
+      .B "void" debugfs_enter_cancellation
+      .BI "(struct file *file "  ","
+      .BI "struct debugfs_cancellation *cancellation "  ");"
+      .SH ARGUMENTS
+      .IP "file" 12
+      the target file
+      .IP "cancellation" 12
+      the operation to execute
+      .SH "SEE ALSO"
+      .PP
+      Kernel file \fBmock_tests/kdoc-drop-ctx-lock.c\fR
+    rst: |
+      .. c:function:: void debugfs_enter_cancellation (struct file *file, struct debugfs_cancellation *cancellation)
+
+         begin a cancellation operation on **file**
+
+      .. container:: kernelindent
+
+        **Parameters**
+
+        ``struct file *file``
+          the target file
+
+        ``struct debugfs_cancellation *cancellation``
+          the operation to execute
+- name: debugfs_leave_cancellation
+  description: mock_tests/kdoc-drop-ctx-lock.c line 152
+  fname: mock_tests/kdoc-drop-ctx-lock.c
+  source: |
+    /**
+     * debugfs_leave_cancellation - wrapup the cancellation operation on @file
+     * @file: the target file
+     * @cancellation: the operation to wrapup
+     */
+    void debugfs_leave_cancellation(struct file *file,
+                                    struct debugfs_cancellation *cancellation) __releases(cancellation)
+    { }
+  expected:
+  - man: |
+      .TH "debugfs_leave_cancellation" 9 "February 2026"  "mock_tests" "Kernel API Manual"
+      .SH NAME
+      debugfs_leave_cancellation \- wrapup the cancellation operation on @file
+      .SH SYNOPSIS
+      .B "void" debugfs_leave_cancellation
+      .BI "(struct file *file "  ","
+      .BI "struct debugfs_cancellation *cancellation "  ");"
+      .SH ARGUMENTS
+      .IP "file" 12
+      the target file
+      .IP "cancellation" 12
+      the operation to wrapup
+      .SH "SEE ALSO"
+      .PP
+      Kernel file \fBmock_tests/kdoc-drop-ctx-lock.c\fR
+    rst: |
+      .. c:function:: void debugfs_leave_cancellation (struct file *file, struct debugfs_cancellation *cancellation)
+
+         wrapup the cancellation operation on **file**
+
+      .. container:: kernelindent
+
+        **Parameters**
+
+        ``struct file *file``
+          the target file
+
+        ``struct debugfs_cancellation *cancellation``
+          the operation to wrapup
+- name: acpi_os_acquire_lock
+  description: mock_tests/kdoc-drop-ctx-lock.c line 161
+  fname: mock_tests/kdoc-drop-ctx-lock.c
+  source: |
+    /**
+     * acpi_os_acquire_lock - Acquire a spinlock.
+     * @lockp: pointer to the spinlock_t.
+     */
+    acpi_cpu_flags acpi_os_acquire_lock(acpi_spinlock lockp)
+            __acquires(lockp)
+    {
+  expected:
+  - man: |
+      .TH "acpi_os_acquire_lock" 9 "February 2026"  "mock_tests" "Kernel API Manual"
+      .SH NAME
+      acpi_os_acquire_lock \- Acquire a spinlock.
+      .SH SYNOPSIS
+      .B "acpi_cpu_flags" acpi_os_acquire_lock
+      .BI "(acpi_spinlock lockp "  ");"
+      .SH ARGUMENTS
+      .IP "lockp" 12
+      pointer to the spinlock_t.
+      .SH "SEE ALSO"
+      .PP
+      Kernel file \fBmock_tests/kdoc-drop-ctx-lock.c\fR
+    rst: |
+      .. c:function:: acpi_cpu_flags acpi_os_acquire_lock (acpi_spinlock lockp)
+
+         Acquire a spinlock.
+
+      .. container:: kernelindent
+
+        **Parameters**
+
+        ``acpi_spinlock lockp``
+          pointer to the spinlock_t.
+- name: acpi_os_release_lock
+  description: mock_tests/kdoc-drop-ctx-lock.c line 172
+  fname: mock_tests/kdoc-drop-ctx-lock.c
+  source: |
+    /**
+     * acpi_os_release_lock - Release a spinlock.
+     * @lockp: pointer to the spinlock_t.
+     * @not_used: these flags are not used.
+     */
+    void acpi_os_release_lock(acpi_spinlock lockp, acpi_cpu_flags not_used)
+            __releases(lockp)
+    {
+  expected:
+  - man: |
+      .TH "acpi_os_release_lock" 9 "February 2026"  "mock_tests" "Kernel API Manual"
+      .SH NAME
+      acpi_os_release_lock \- Release a spinlock.
+      .SH SYNOPSIS
+      .B "void" acpi_os_release_lock
+      .BI "(acpi_spinlock lockp "  ","
+      .BI "acpi_cpu_flags not_used "  ");"
+      .SH ARGUMENTS
+      .IP "lockp" 12
+      pointer to the spinlock_t.
+      .IP "not_used" 12
+      these flags are not used.
+      .SH "SEE ALSO"
+      .PP
+      Kernel file \fBmock_tests/kdoc-drop-ctx-lock.c\fR
+    rst: |
+      .. c:function:: void acpi_os_release_lock (acpi_spinlock lockp, acpi_cpu_flags not_used)
+
+         Release a spinlock.
+
+      .. container:: kernelindent
+
+        **Parameters**
+
+        ``acpi_spinlock lockp``
+          pointer to the spinlock_t.
+
+        ``acpi_cpu_flags not_used``
+          these flags are not used.
+- name: tx
+  description: mock_tests/kdoc-drop-ctx-lock.c line 183
+  fname: mock_tests/kdoc-drop-ctx-lock.c
+  source: |
+    /**
+     * tx - transmit message ID @id
+     * @id: message ID to transmit
+     */
+    int tx(int id) __must_hold(&txlock)
+    {
+  expected:
+  - man: |
+      .TH "tx" 9 "February 2026"  "mock_tests" "Kernel API Manual"
+      .SH NAME
+      tx \- transmit message ID @id
+      .SH SYNOPSIS
+      .B "int" tx
+      .BI "(int id "  ");"
+      .SH ARGUMENTS
+      .IP "id" 12
+      message ID to transmit
+      .SH "SEE ALSO"
+      .PP
+      Kernel file \fBmock_tests/kdoc-drop-ctx-lock.c\fR
+    rst: |
+      .. c:function:: int tx (int id)
+
+         transmit message ID **id**
+
+      .. container:: kernelindent
+
+        **Parameters**
+
+        ``int id``
+          message ID to transmit
+- name: contend_for_bm
+  description: mock_tests/kdoc-drop-ctx-lock.c line 192
+  fname: mock_tests/kdoc-drop-ctx-lock.c
+  source: |
+    /**
+     * contend_for_bm - try to become the bus master
+     * @card: the &fw_card (describes the bus)
+     */
+    enum bm_contention_outcome contend_for_bm(struct fw_card *card)
+        __must_hold(&card->lock)
+    {
+  expected:
+  - man: |
+      .TH "contend_for_bm" 9 "February 2026"  "mock_tests" "Kernel API Manual"
+      .SH NAME
+      contend_for_bm \- try to become the bus master
+      .SH SYNOPSIS
+      .B "enum bm_contention_outcome" contend_for_bm
+      .BI "(struct fw_card *card "  ");"
+      .SH ARGUMENTS
+      .IP "card" 12
+      the \fIfw_card\fP (describes the bus)
+      .SH "SEE ALSO"
+      .PP
+      Kernel file \fBmock_tests/kdoc-drop-ctx-lock.c\fR
+    rst: |
+      .. c:function:: enum bm_contention_outcome contend_for_bm (struct fw_card *card)
+
+         try to become the bus master
+
+      .. container:: kernelindent
+
+        **Parameters**
+
+        ``struct fw_card *card``
+          the :c:type:`fw_card` (describes the bus)
+- name: prepare_report_producer
+  description: mock_tests/kdoc-drop-ctx-lock.c line 202
+  fname: mock_tests/kdoc-drop-ctx-lock.c
+  source: |
+    /**
+     * prepare_report_producer - prepare the report producer
+     * @flags: still flags
+     * @ai: some AI
+     * @other_info: Populate @other_info; requires that the provided
+     *   @other_info not in use.
+     */
+    void prepare_report_producer(unsigned long *flags,
+                                const struct access_info *ai,
+                                struct other_info *other_info)
+            __must_not_hold(&report_lock)
+    { }
+  expected:
+  - man: |
+      .TH "prepare_report_producer" 9 "February 2026"  "mock_tests" "Kernel API Manual"
+      .SH NAME
+      prepare_report_producer \- prepare the report producer
+      .SH SYNOPSIS
+      .B "void" prepare_report_producer
+      .BI "(unsigned long *flags "  ","
+      .BI "const struct access_info *ai "  ","
+      .BI "struct other_info *other_info "  ");"
+      .SH ARGUMENTS
+      .IP "flags" 12
+      still flags
+      .IP "ai" 12
+      some AI
+      .IP "other_info" 12
+      Populate \fIother_info\fP; requires that the provided
+      \fIother_info\fP not in use.
+      .SH "SEE ALSO"
+      .PP
+      Kernel file \fBmock_tests/kdoc-drop-ctx-lock.c\fR
+    rst: |
+      .. c:function:: void prepare_report_producer (unsigned long *flags, const struct access_info *ai, struct other_info *other_info)
+
+         prepare the report producer
+
+      .. container:: kernelindent
+
+        **Parameters**
+
+        ``unsigned long *flags``
+          still flags
+
+        ``const struct access_info *ai``
+          some AI
+
+        ``struct other_info *other_info``
+          Populate **other_info**; requires that the provided
+          **other_info** not in use.
+- name: crypto_alg_lookup
+  description: mock_tests/kdoc-drop-ctx-lock.c line 215
+  fname: mock_tests/kdoc-drop-ctx-lock.c
+  source: |
+    /**
+     * __crypto_alg_lookup() - lookup the algorithm by name/type/mask
+     * @name: name to search for
+     * @type: type to search for
+     * @mask: mask to match
+     */
+    struct crypto_alg *__crypto_alg_lookup(const char *name, u32 type,
+                                                  u32 mask)
+            __must_hold_shared(&crypto_alg_sem)
+    {
+  expected:
+  - man: |
+      .TH "__crypto_alg_lookup" 9 "February 2026"  "mock_tests" "Kernel API Manual"
+      .SH NAME
+      __crypto_alg_lookup \- lookup the algorithm by name/type/mask
+      .SH SYNOPSIS
+      .B "struct crypto_alg *" __crypto_alg_lookup
+      .BI "(const char *name "  ","
+      .BI "u32 type "  ","
+      .BI "u32 mask "  ");"
+      .SH ARGUMENTS
+      .IP "name" 12
+      name to search for
+      .IP "type" 12
+      type to search for
+      .IP "mask" 12
+      mask to match
+      .SH "SEE ALSO"
+      .PP
+      Kernel file \fBmock_tests/kdoc-drop-ctx-lock.c\fR
+    rst: |
+      .. c:function:: struct crypto_alg * __crypto_alg_lookup (const char *name, u32 type, u32 mask)
+
+         lookup the algorithm by name/type/mask
+
+      .. container:: kernelindent
+
+        **Parameters**
+
+        ``const char *name``
+          name to search for
+
+        ``u32 type``
+          type to search for
+
+        ``u32 mask``
+          mask to match
+- name: down_read_trylock
+  description: mock_tests/kdoc-drop-ctx-lock.c line 228
+  fname: mock_tests/kdoc-drop-ctx-lock.c
+  source: |
+    /**
+     * down_read_trylock - trylock for reading
+     * @sem: the semaphore to try to lock
+     *
+     * Returns: 1 if successful, 0 if contention
+     */
+    extern int down_read_trylock(struct rw_semaphore *sem) __cond_acquires_shared(true, sem);
+  expected:
+  - man: |
+      .TH "down_read_trylock" 9 "February 2026"  "mock_tests" "Kernel API Manual"
+      .SH NAME
+      down_read_trylock \- trylock for reading
+      .SH SYNOPSIS
+      .B "int" down_read_trylock
+      .BI "(struct rw_semaphore *sem "  ");"
+      .SH ARGUMENTS
+      .IP "sem" 12
+      the semaphore to try to lock
+      .SH "RETURN"
+      1 if successful, 0 if contention
+      .SH "SEE ALSO"
+      .PP
+      Kernel file \fBmock_tests/kdoc-drop-ctx-lock.c\fR
+    rst: |
+      .. c:function:: int down_read_trylock (struct rw_semaphore *sem)
+
+         trylock for reading
+
+      .. container:: kernelindent
+
+        **Parameters**
+
+        ``struct rw_semaphore *sem``
+          the semaphore to try to lock
+
+        **Return**
+
+        1 if successful, 0 if contention
+- name: tomoyo_read_lock
+  description: mock_tests/kdoc-drop-ctx-lock.c line 236
+  fname: mock_tests/kdoc-drop-ctx-lock.c
+  source: |
+    /**
+     * tomoyo_read_lock - Take lock for protecting policy.
+     *
+     * Returns: index number for tomoyo_read_unlock().
+     */
+    int tomoyo_read_lock(void)
+            __acquires_shared(&tomoyo_ss)
+    {
+  expected:
+  - man: |
+      .TH "tomoyo_read_lock" 9 "February 2026"  "mock_tests" "Kernel API Manual"
+      .SH NAME
+      tomoyo_read_lock \- Take lock for protecting policy.
+      .SH SYNOPSIS
+      .B "int" tomoyo_read_lock
+      .BI "(void "  ");"
+      .SH ARGUMENTS
+      .IP "void" 12
+      no arguments
+      .SH "RETURN"
+      index number for \fBtomoyo_read_unlock\fP.
+      .SH "SEE ALSO"
+      .PP
+      Kernel file \fBmock_tests/kdoc-drop-ctx-lock.c\fR
+    rst: |
+      .. c:function:: int tomoyo_read_lock (void)
+
+         Take lock for protecting policy.
+
+      .. container:: kernelindent
+
+        **Parameters**
+
+        ``void``
+          no arguments
+
+        **Return**
+
+        index number for tomoyo_read_unlock().
+- name: tomoyo_read_unlock
+  description: mock_tests/kdoc-drop-ctx-lock.c line 247
+  fname: mock_tests/kdoc-drop-ctx-lock.c
+  source: |
+    /**
+     * tomoyo_read_unlock - Release lock for protecting policy.
+     *
+     * @idx: Index number returned by tomoyo_read_lock().
+     */
+    void tomoyo_read_unlock(int idx)
+            __releases_shared(&tomoyo_ss)
+    { }
+  expected:
+  - man: |
+      .TH "tomoyo_read_unlock" 9 "February 2026"  "mock_tests" "Kernel API Manual"
+      .SH NAME
+      tomoyo_read_unlock \- Release lock for protecting policy.
+      .SH SYNOPSIS
+      .B "void" tomoyo_read_unlock
+      .BI "(int idx "  ");"
+      .SH ARGUMENTS
+      .IP "idx" 12
+      Index number returned by \fBtomoyo_read_lock\fP.
+      .SH "SEE ALSO"
+      .PP
+      Kernel file \fBmock_tests/kdoc-drop-ctx-lock.c\fR
+    rst: |
+      .. c:function:: void tomoyo_read_unlock (int idx)
+
+         Release lock for protecting policy.
+
+      .. container:: kernelindent
+
+        **Parameters**
+
+        ``int idx``
+          Index number returned by tomoyo_read_lock().
+- name: c_stop
+  description: mock_tests/kdoc-drop-ctx-lock.c line 256
+  fname: mock_tests/kdoc-drop-ctx-lock.c
+  source: |
+    /**
+     * c_stop - stop the seq_file iteration
+     * @m: the &struct seq_file
+     * @p: handle
+     */
+    void c_stop(struct seq_file *m, void *p)
+            __releases_shared(&crypto_alg_sem)
+    { }
+  expected:
+  - man: |
+      .TH "c_stop" 9 "February 2026"  "mock_tests" "Kernel API Manual"
+      .SH NAME
+      c_stop \- stop the seq_file iteration
+      .SH SYNOPSIS
+      .B "void" c_stop
+      .BI "(struct seq_file *m "  ","
+      .BI "void *p "  ");"
+      .SH ARGUMENTS
+      .IP "m" 12
+      the \fIstruct seq_file\fP
+      .IP "p" 12
+      handle
+      .SH "SEE ALSO"
+      .PP
+      Kernel file \fBmock_tests/kdoc-drop-ctx-lock.c\fR
+    rst: |
+      .. c:function:: void c_stop (struct seq_file *m, void *p)
+
+         stop the seq_file iteration
+
+      .. container:: kernelindent
+
+        **Parameters**
+
+        ``struct seq_file *m``
+          the :c:type:`struct seq_file <seq_file>`
+
+        ``void *p``
+          handle
+- name: spin_lock
+  description: mock_tests/kdoc-drop-ctx-lock.c line 265
+  fname: mock_tests/kdoc-drop-ctx-lock.c
+  source: |
+    /**
+     * spin_lock - spin until the @lock is acquired
+     * @lock: the spinlock
+     */
+    void spin_lock(spinlock_t *lock)
+            __acquires(lock) __no_context_analysis
+    { }
+  expected:
+  - man: |
+      .TH "spin_lock" 9 "February 2026"  "mock_tests" "Kernel API Manual"
+      .SH NAME
+      spin_lock \- spin until the @lock is acquired
+      .SH SYNOPSIS
+      .B "void" spin_lock
+      .BI "(spinlock_t *lock "  ");"
+      .SH ARGUMENTS
+      .IP "lock" 12
+      the spinlock
+      .SH "SEE ALSO"
+      .PP
+      Kernel file \fBmock_tests/kdoc-drop-ctx-lock.c\fR
+    rst: |
+      .. c:function:: void spin_lock (spinlock_t *lock)
+
+         spin until the **lock** is acquired
+
+      .. container:: kernelindent
+
+        **Parameters**
+
+        ``spinlock_t *lock``
+          the spinlock
-- 
2.52.0

[PATCH 7/7] docs: kdoc_output: fix handling of simple tables

[Mauro Carvalho Chehab]

Fix check for simple table delimiters.

ReST simple tables use "=" instead of "-". I ended testing it with
a table modified from a complex one, using "--- --- ---", instead
of searching for a real Kernel example.

Only noticed when adding an unit test and seek for an actual
example from kernel-doc markups.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 tools/lib/python/kdoc/kdoc_output.py | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/tools/lib/python/kdoc/kdoc_output.py b/tools/lib/python/kdoc/kdoc_output.py
index 1b54117dbe19..2bfcd356654b 100644
--- a/tools/lib/python/kdoc/kdoc_output.py
+++ b/tools/lib/python/kdoc/kdoc_output.py
@@ -846,14 +846,14 @@ class ManFormat(OutputFormat):
         colspec_row = None
 
         pos = []
-        for m in KernRe(r'\-+').finditer(lines[i]):
+        for m in KernRe(r'\=+').finditer(lines[i]):
             pos.append((m.start(), m.end() - 1))
 
         i += 1
         while i < len(lines):
             line = lines[i]
 
-            if KernRe(r"^\s*[\-]+[ \t\-]+$").match(line):
+            if KernRe(r"^\s*[\=]+[ \t\=]+$").match(line):
                 i += 1
                 break
 
@@ -969,7 +969,7 @@ class ManFormat(OutputFormat):
                     self.data += text
                     continue
 
-                if KernRe(r"^\-+[ \t]\-[ \t\-]+$").match(line):
+                if KernRe(r"^\=+[ \t]\=[ \t\=]+$").match(line):
                     i, text = self.simple_table(lines, i)
                     self.data += text
                     continue
-- 
2.52.0

Re: [PATCH 0/7] More kernel-doc unit tests

[Jonathan Corbet]

Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:

> 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.

I've applied these, thanks.

jon

Re: [PATCH 0/7] More kernel-doc unit tests

[Jonathan Corbet]

Jonathan Corbet <corbet@lwn.net> writes:

> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
>
>> 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.
>
> I've applied these, thanks.

Actually nevermind...it appears that this series was superseded by the
set sent on Monday?  I've applied the newer set instead.

Thanks,

jon