Re: [PATCH 4/5] slab: Set freed variables to NULL by default

[Matthew Wilcox <willy@infradead.org>]

On Fri, Mar 21, 2025 at 01:41:00PM -0700, Kees Cook wrote:
>  /**
> - * kfree - free previously allocated memory
> + * __kfree - free previously allocated memory

No.  After applying this patch, we now have documentation for __kfree --
a function we want precisely 0 people to call directly, and no
documentation for kfree(), which is the function we want everybody to
use.

I don't know what the right solution to kernel documentation is here,
but this is definitely not it.  Something I've done in the past is to
note that kernel-doc ignores preprocessor, so we could do something
like:

#if 0
/**
 * kfree - blah blah
 * @blah: blah
 *
 * blah blah blah
 */
void kfree(const void *object) { }
#endif
void __kfree(const void *object)
{
...
}

We'd get warnings if people asked the kbuild system to show them all
EXPORT_SYMBOL functions which don't have kdoc, but nobody's that
invested in having complete documentation.  I don't know if this is
a good approach to solving the problem.