Re: [PATCH] docs: kdoc: strip DOMAIN_NS() wrapper in function prototypes

[Randy Dunlap]

On 10/1/26 9:15 PM, Omokefe Emmanuel Onanaroghene wrote:
> kernel-doc fails to parse functions whose names are wrapped in the
> DOMAIN_NS() namespace macro, e.g. in
> drivers/iommu/generic_pt/iommu_pt.h:217:
> 
>   ... expecting prototype for iova_to_phys(). Prototype was for
>   DOMAIN_NS() instead
> 
> function_xforms is the designated place for unwrapping function-name
> macros, but it has no entry for DOMAIN_NS(), so the macro name is kept
> as the prototype and the real name leaks into the parameter list.
> 
> Add a transform expanding DOMAIN_NS(op) to op, following the existing
> DEFINE_IDTENTRY_IRQ precedent.
> 
> Add a regression test for the wrapped iova_to_phys() declaration.
> 
> Signed-off-by: Omokefe Emmanuel Onanaroghene <emmaonana18@xxxxxxxxx>

Tested-by: Randy Dunlap <rdunlap@xxxxxxxxxxxxx>
Acked-by: Randy Dunlap <rdunlap@xxxxxxxxxxxxx>

Thanks.

> ---
>  tools/lib/python/kdoc/xforms_lists.py |  6 ++++++
>  tools/unittests/test_kdoc_parser.py   | 22 ++++++++++++++++++++++
>  2 files changed, 28 insertions(+)
> 
> diff --git a/tools/lib/python/kdoc/xforms_lists.py b/tools/lib/python/kdoc/xforms_lists.py
> index e3dda2fe8a53..5e8bd9117895 100644
> --- a/tools/lib/python/kdoc/xforms_lists.py
> +++ b/tools/lib/python/kdoc/xforms_lists.py
> @@ -91,6 +91,12 @@ class CTransforms:
>          (CMatch("__diagnose_as"), ""),
>          (CMatch("DECL_BUCKET_PARAMS"), r"\1, \2"),
>          (CMatch("DEFINE_IDTENTRY_IRQ"), r"static void \1(struct pt_regs *regs, u32 vector)"),
> +        #
> +        # DOMAIN_NS() wraps a function name with a namespace prefix
> +        # (see drivers/iommu/generic_pt/iommu_pt.h). Unwrap it so the
> +        # real function name is parsed.
> +        #
> +        (CMatch("DOMAIN_NS"), r"\1"),
>          (CMatch("__cond_acquires"), ""),
>          (CMatch("__cond_releases"), ""),
>          (CMatch("__acquires"), ""),
> diff --git a/tools/unittests/test_kdoc_parser.py b/tools/unittests/test_kdoc_parser.py
> index c4a76ed13dbc..4b47a858824a 100755
> --- a/tools/unittests/test_kdoc_parser.py
> +++ b/tools/unittests/test_kdoc_parser.py
> @@ -418,6 +418,28 @@ class TestSelfValidate(GenerateKdocItem):
>          """
>          self.run_test(self.SOURCE, [self.DEFAULT.copy()], self.EXPORTS)
>  
> +class TestDomainNs(GenerateKdocItem):
> +    def test_domain_ns_wrapped_function(self):
> +        source = """
> +            /**
> +             * iova_to_phys() - Return the output address for the given IOVA
> +             * @domain: Table to query
> +             * @iova: IO virtual address to query
> +             */
> +            phys_addr_t DOMAIN_NS(iova_to_phys)(struct iommu_domain *domain,
> +                                                dma_addr_t iova);
> +        """
> +
> +        kernel_doc = KernelDoc(self.config, "test.c", self.xforms)
> +        patcher = patch('builtins.open', new_callable=mock_open,
> +                        read_data=dedent(source))
> +        with patcher:
> +            _, entries = kernel_doc.parse_kdoc()
> +
> +        self.assertEqual(len(entries), 1)
> +        self.assertEqual(entries[0].name, "iova_to_phys")
> +        self.assertEqual(entries[0].warnings, [])
> +
>  #
>  # Class and logic to create dynamic tests from YAML
>  #

-- 
~Randy