Re: [PATCH] docs: kdoc_output: don't add a man page tail for filtered-out symbols

[Randy Dunlap <rdunlap@infradead.org>]

Hi Simon,

On 9/29/26 6:36 AM, Simon Sudarushkin via B4 Relay wrote:
> From: Simon Sudarushkin <simonsudarushkin@gmail.com>
> 
> ManFormat.msg() appends the "SEE ALSO" tail after every call to the base
> class msg(), even when the -e, -i, -s or --nosymbol filters dropped the
> symbol and nothing was written for it. With -s, every other symbol in
> the file leaves a stray "SEE ALSO" block behind the requested page. With
> -e on a file that exports nothing, the output is only such blocks, with
> no .TH header at all:
> 
>   $ tools/docs/kernel-doc -man -s string_get_size lib/string_helpers.c \
>       | grep -c 'SEE ALSO'
>   13
>   $ tools/docs/kernel-doc -man -e include/rdma/ib_mad.h | grep -c '^\.TH'
>   0
> 
> Only add the tail when the base class produced a page, and add unit
> tests for both cases.
> 
> Reported-by: Randy Dunlap <rdunlap@infradead.org>
> Closes: https://lore.kernel.org/all/fc7978bb-a71f-456d-84bb-670c8f0426ed@infradead.org/
> Fixes: 104e0a682e12 ("tools: kernel-doc: add a see also section at man pages")
> Assisted-by: LLM
> Signed-off-by: Simon Sudarushkin <simonsudarushkin@gmail.com>
> ---
> Randy, this takes a different route from your patch in August [1]: the
> out_tail() call stays in ManFormat.msg() and is skipped when the base
> class produced no page, so OutputFormat does not need to know about it.
> DOC blocks that are shown keep their tail, since they get their own .TH.

Yes, I had already abandoned that patch and its approach. I was (slowly)
looking at doing something like this, although probably not as succinct
as this.

Tested-by: Randy Dunlap <rdunlap@infradead.org>
Acked-by: Randy Dunlap <rdunlap@infradead.org>

Thanks.


> 
> [1] https://lore.kernel.org/all/20260816054826.3988516-1-rdunlap@infradead.org/
> ---
>  tools/lib/python/kdoc/kdoc_output.py |  5 +++-
>  tools/unittests/test_kdoc_parser.py  | 52 ++++++++++++++++++++++++++++++++++++
>  2 files changed, 56 insertions(+), 1 deletion(-)
> 
> diff --git a/tools/lib/python/kdoc/kdoc_output.py b/tools/lib/python/kdoc/kdoc_output.py
> index 618b0d765ef5..659a2c6fb6be 100644
> --- a/tools/lib/python/kdoc/kdoc_output.py
> +++ b/tools/lib/python/kdoc/kdoc_output.py
> @@ -763,7 +763,10 @@ class ManFormat(OutputFormat):
>          Add a tail at the end of man pages output.
>          """
>          super().msg(fname, name, args)
> -        self.out_tail(fname, name, args)
> +
> +        # Symbols dropped by the output filters produce no page
> +        if self.data:
> +            self.out_tail(fname, name, args)
>  
>          return self.data
>  
> diff --git a/tools/unittests/test_kdoc_parser.py b/tools/unittests/test_kdoc_parser.py
> index c4a76ed13dbc..bcb1b1a5ccc6 100755
> --- a/tools/unittests/test_kdoc_parser.py
> +++ b/tools/unittests/test_kdoc_parser.py
> @@ -301,6 +301,58 @@ class CToMan(unittest.TestCase):
>          self.assertEqual(result, expected)
>  
>  
> +class ManFilterTail(unittest.TestCase):
> +    """
> +    Symbols dropped by the output filters must not leave a man page tail.
> +    """
> +
> +    source = dedent("""
> +        /**
> +         * foo - First function
> +         * @a: an argument
> +         */
> +        int foo(int a) { return 0; };
> +
> +        /**
> +         * bar - Second function
> +         * @b: an argument
> +         */
> +        int bar(int b) { return 0; };
> +    """)
> +
> +    def setUp(self):
> +        config = MockKdocConfig()
> +        kernel_doc = KernelDoc(config, "mock.c", CTransforms())
> +
> +        with patch('builtins.open', new_callable=mock_open,
> +                   read_data=self.source):
> +            _, self.entries = kernel_doc.parse_kdoc()
> +
> +        self.out_style = ManFormat()
> +        self.out_style.set_config(config)
> +
> +    def run_filter(self, **kwargs):
> +        args = {"export": False, "internal": False, "symbol": None,
> +                "nosymbol": None, "function_table": set(),
> +                "enable_lineno": False, "no_doc_sections": False}
> +        args.update(kwargs)
> +
> +        self.out_style.set_filter(**args)
> +
> +        return self.out_style.output_symbols("mock.c", self.entries)
> +
> +    def test_symbol_filter(self):
> +        """Only the selected symbol gets a page, with a single tail."""
> +        result = self.run_filter(symbol=["foo"], function_table={"foo"})
> +
> +        self.assertEqual(result.count(".TH "), 1)
> +        self.assertEqual(result.count('.SH "SEE ALSO"'), 1)
> +
> +    def test_all_filtered_out(self):
> +        """No exported symbols: no output at all."""
> +        self.assertEqual(self.run_filter(export=True), "")
> +
> +
>  class CToRest(unittest.TestCase):
>      out_style = RestFormat()
>      config = MockKdocConfig()
> 
> ---
> base-commit: 4f041d7b65b8007403cce30ecf69ad42d48ec315
> change-id: 20260929-kdoc-man-filter-eba1ff857dad
> 
> Best regards,
> --  
> Simon Sudarushkin <simonsudarushkin@gmail.com>


-- 
~Randy