Re: [PATCH v3 2/2] slab: fix kernel-docs for mm-api
On Mon, 11 May 2026 at 14:19, Jonathan Corbet wrote: > > Marco Elver writes: > > > 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. > > I'm going to be a while catching up with things, so this is just a first > take. I strongly suspect that the people who object so strongly to > documentation markup in general would be less than fully thrilled by the > addition of this kind of workaround. I'd like to ponder a bit and see > if I can some up with something better...but again, it won't happen > right away. Thanks, Jon. The technical debt (hacks) that would accumulate in the kernel-doc parser just for accommodating slab.h might be quite high; slab.h is rather special, so the "#if 0" solution might be justified. Then again, if there's a reasonable kernel-doc parser solution, that also helps in other places, I won't object. I tested the "#if 0" version and it works as expected. So to move forward, we could consider it in the short term, and in the longer term, see what new powers the kernel-doc parser can provide.
Re: [PATCH v3 2/2] slab: fix kernel-docs for mm-api
Marco Elver writes: > 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. I'm going to be a while catching up with things, so this is just a first take. I strongly suspect that the people who object so strongly to documentation markup in general would be less than fully thrilled by the addition of this kind of workaround. I'd like to ponder a bit and see if I can some up with something better...but again, it won't happen right away. Thanks, jon
Re: [PATCH v3 2/2] slab: fix kernel-docs for mm-api
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)
>> 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
>> >
>> > +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.
Re: [PATCH v3 2/2] slab: fix kernel-docs for mm-api
On Thu, Apr 30, 2026 at 03:59PM +0200, Marco Elver wrote:
> On Thu, 30 Apr 2026 at 15:40, Vlastimil Babka (SUSE)
> 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
> >
> > +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.
-- >8 --
From: Marco Elver
Date: Tue, 21 Apr 2026 13:48:21 +0200
Subject: [PATCH] slab: fix kernel-docs for mm-api
The mm-api kernel-docs have been disconnected from their symbols. While
the scripts were previously taught to handle the _noprof suffix added by
allocation tagging (in 51a7bf0238c2 "scripts/kernel-doc: drop "_noprof"
on function prototypes"), this does not handle cases where the internal
implementation function has an additional leading underscore. The added
optional parameters (via DECL_KMALLOC_PARAMS) further complicate parsing
the internal signatures.
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.
Simply moving the docs to the macros in slab.h fixes the association but
causes loss of types in the generated documentation (rendering as e.g.
untyped 'kmalloc(size, flags)' macro).
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. Providing explicit, typed C prototypes for the documented APIs inside
'#if 0 /* kernel-doc */' blocks.
3. Converting the variadic macros for the documented APIs to use
explicit arguments to match the documentation.
No functional change intended.
Signed-off-by: Marco Elver
---
v4:
* Provide typed C prototypes in '#if 0' blocks to properly render API.
---
include/linux/slab.h | 216 +--
mm/slub.c| 98
2 files changed, 168 insertions(+), 146 deletions(-)
diff --git a/include/linux/slab.h b/include/linux/slab.h
index c232f8a10af6..5e1249e36b0d 100644
--- a/include/linux/slab.h
+++ b/include/linux/slab.h
@@ -530,7 +530,49 @@ void * __must_check krealloc_node_align_noprof(const void
*objp,
unsigned long align,
gfp_t flags, int nid)
__realloc_size(2);
#define krealloc_noprof(_o, _s, _f)krealloc_node_align_noprof(_o,
PASS_TOKEN_PARAMS(_s, __kmalloc_token(_s)), 1, _f, NUMA_NO_NODE)
-#define krealloc_node_align(_o, _s, _a, _f, _n)
alloc_hooks(krealloc_node_align_noprof(_o, PASS_TOKEN_PARAMS(_s,
__kmalloc_token(_s)), _a, _f, _n))
+#if 0 /* kernel-doc */
+/**
+ * krealloc_node_align - reallocate memory. The contents will remain unchanged.
+ * @p: object to reallocate memory for.
+ * @new_size: how many bytes of memory are required.
+ * @align: desired alignment.
+ * @flags: the type of memory to allocate.
+ * @nid: NUMA node or NUMA_NO_NODE
+ *
+ * If @p is %NULL, krealloc() behaves exactly like kmalloc(). If @new_size
+ * is 0 and @p is not a %NULL pointer, the object pointed to is freed.
+ *
+ * Only alignments up to those guaranteed by kmalloc() will be honored. Please
Re: [PATCH v3 2/2] slab: fix kernel-docs for mm-api
On Thu, 30 Apr 2026 at 15:40, Vlastimil Babka (SUSE) 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
>
> +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?
Re: [PATCH v3 2/2] slab: fix kernel-docs for mm-api
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
+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?
