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

[Jonathan Corbet]

Simon Sudarushkin via B4 Relay
<devnull+simonsudarushkin.gmail.com@xxxxxxxxxx> writes:

> From: Simon Sudarushkin <simonsudarushkin@xxxxxxxxx>
>
> 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@xxxxxxxxxxxxx>
> Closes: https://lore.kernel.org/all/fc7978bb-a71f-456d-84bb-670c8f0426ed@xxxxxxxxxxxxx/
> Fixes: 104e0a682e12 ("tools: kernel-doc: add a see also section at man pages")
> Assisted-by: LLM
> Signed-off-by: Simon Sudarushkin <simonsudarushkin@xxxxxxxxx>
> ---
> 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.
>
> [1] https://lore.kernel.org/all/20260816054826.3988516-1-rdunlap@xxxxxxxxxxxxx/
> ---
>  tools/lib/python/kdoc/kdoc_output.py |  5 +++-
>  tools/unittests/test_kdoc_parser.py  | 52 ++++++++++++++++++++++++++++++++++++
>  2 files changed, 56 insertions(+), 1 deletion(-)

Applied, thanks.

jon