Re: [PATCH v3 2/2] slab: fix kernel-docs for mm-api

["Vlastimil Babka (SUSE)" <vbabka@kernel.org>]

On 5/4/26 17:00, Marco Elver wrote:
> On Thu, Apr 30, 2026 at 03:59PM +0200, Marco Elver wrote:
>> On Thu, 30 Apr 2026 at 15:40, Vlastimil Babka (SUSE) <vbabka@kernel.org> wrote:
>> >
>> > On 4/24/26 15:24, Marco Elver wrote:
>> > > The mm-api kernel-doc comments have been broken for a while, as many
>> > > documented symbols shifted from being direct function definitions to
>> > > macros wrapping _noprof implementations during the introduction of
>> > > allocation tagging (starting with commit 7bd230a26648 "mm/slab: enable
>> > > slab allocation tagging for kmalloc and friends").
>> > >
>> > > When the kernel-doc block remains above the internal implementation
>> > > function but uses the public API name, the documentation generator fails
>> > > to associate the documented symbol and generates warnings and fails to
>> > > emit the documentation.
>> > >
>> > > Fix this by:
>> > >
>> > > 1. Moving the kernel-doc comment blocks from slub.c to slab.h, placing
>> > >    them directly above the user-facing macros.
>> > >
>> > > 2. Converting the variadic macros for the documented APIs to use
>> > >    explicit arguments.
>> > >
>> > > No functional change intended.
>> > >
>> > > Signed-off-by: Marco Elver <elver@google.com>
>> >
>> > +Cc Jon
>> >
>> > I thought it was supposed to work because the kernel-doc scripts were at the
>> > time taught by commit 51a7bf0238c2 ("scripts/kernel-doc: drop "_noprof" on
>> > function prototypes") to handle _noprof. In the current form git grep finds:
>> >
>> > tools/lib/python/kdoc/kdoc_parser.py:        suffixes = [ '_noprof' ]
>> > tools/lib/python/kdoc/xforms_lists.py:        (KernRe("_noprof"), ""),
>> >
>> > Doesn't it work for you then?
>> 
>> Ah, I see. So it doesn't work anymore because we add the '_' prefix, too.
>> 
>> I guess the question is if we want to proliferate more kdoc parser
>> special cases, or just move the docs to the macros. The downside of
>> macros is that they lose the types in the displayed function
>> signature.
>> 
>> Preferences?
> 
> How about the below, i.e. adding type decls that only the kernel-doc
> parser sees? One complication is also DECL_KMALLOC_PARAMS, and adding
> kernel-doc parser hacks for that looks pretty awful, so this is a lot
> cleaner.

Looks like a good workaround to me, unless something gets confused by seeing
both the declaration and the define.