[PATCH] mm/slab: fix kernel-doc func param names

[PATCH] mm/slab: fix kernel-doc func param names

[Randy Dunlap]

Use corrected function parameter names to eliminate kernel-doc
warnings:

slab.h:142: warning: Function parameter or struct member 's' not described in 'slab_folio'
slab.h:142: warning: Excess function parameter 'slab' description in 'slab_folio'
slab.h:168: warning: Function parameter or struct member 's' not described in 'slab_page'
slab.h:168: warning: Excess function parameter 'slab' description in 'slab_page'

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: Christoph Lameter <cl@linux.com>
Cc: Pekka Enberg <penberg@kernel.org>
Cc: David Rientjes <rientjes@google.com>
Cc: Joonsoo Kim <iamjoonsoo.kim@lge.com>
Cc: Andrew Morton <akpm@linux-foundation.org>
Cc: Vlastimil Babka <vbabka@suse.cz>
---
 mm/slab.h |    4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

--- linux-next-20250108.orig/mm/slab.h
+++ linux-next-20250108/mm/slab.h
@@ -128,7 +128,7 @@ static_assert(IS_ALIGNED(offsetof(struct
 
 /**
  * slab_folio - The folio allocated for a slab
- * @slab: The slab.
+ * @s: The slab.
  *
  * Slabs are allocated as folios that contain the individual objects and are
  * using some fields in the first struct page of the folio - those fields are
@@ -159,7 +159,7 @@ static_assert(IS_ALIGNED(offsetof(struct
 
 /**
  * slab_page - The first struct page allocated for a slab
- * @slab: The slab.
+ * @s: The slab.
  *
  * A convenience wrapper for converting slab to the first struct page of the
  * underlying folio, to communicate with code not yet converted to folio or

Re: [PATCH] mm/slab: fix kernel-doc func param names

[Vlastimil Babka]

On 1/11/25 07:32, Randy Dunlap wrote:
> Use corrected function parameter names to eliminate kernel-doc
> warnings:
> 
> slab.h:142: warning: Function parameter or struct member 's' not described in 'slab_folio'
> slab.h:142: warning: Excess function parameter 'slab' description in 'slab_folio'
> slab.h:168: warning: Function parameter or struct member 's' not described in 'slab_page'
> slab.h:168: warning: Excess function parameter 'slab' description in 'slab_page'

I'm unable to get those warnings with "make htmldocs", what exactly do I
need to run?

> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
> Cc: Christoph Lameter <cl@linux.com>
> Cc: Pekka Enberg <penberg@kernel.org>
> Cc: David Rientjes <rientjes@google.com>
> Cc: Joonsoo Kim <iamjoonsoo.kim@lge.com>
> Cc: Andrew Morton <akpm@linux-foundation.org>
> Cc: Vlastimil Babka <vbabka@suse.cz>

Anyway the problem and fix seem obvious, so applied. Thanks!

> ---
>  mm/slab.h |    4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
> 
> --- linux-next-20250108.orig/mm/slab.h
> +++ linux-next-20250108/mm/slab.h
> @@ -128,7 +128,7 @@ static_assert(IS_ALIGNED(offsetof(struct
>  
>  /**
>   * slab_folio - The folio allocated for a slab
> - * @slab: The slab.
> + * @s: The slab.
>   *
>   * Slabs are allocated as folios that contain the individual objects and are
>   * using some fields in the first struct page of the folio - those fields are
> @@ -159,7 +159,7 @@ static_assert(IS_ALIGNED(offsetof(struct
>  
>  /**
>   * slab_page - The first struct page allocated for a slab
> - * @slab: The slab.
> + * @s: The slab.
>   *
>   * A convenience wrapper for converting slab to the first struct page of the
>   * underlying folio, to communicate with code not yet converted to folio or

Re: [PATCH] mm/slab: fix kernel-doc func param names

[Randy Dunlap]

Hi,

On 1/11/25 12:12 PM, Vlastimil Babka wrote:
> On 1/11/25 07:32, Randy Dunlap wrote:
>> Use corrected function parameter names to eliminate kernel-doc
>> warnings:
>>
>> slab.h:142: warning: Function parameter or struct member 's' not described in 'slab_folio'
>> slab.h:142: warning: Excess function parameter 'slab' description in 'slab_folio'
>> slab.h:168: warning: Function parameter or struct member 's' not described in 'slab_page'
>> slab.h:168: warning: Excess function parameter 'slab' description in 'slab_page'
> 
> I'm unable to get those warnings with "make htmldocs", what exactly do I
> need to run?
> 
>> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
>> Cc: Christoph Lameter <cl@linux.com>
>> Cc: Pekka Enberg <penberg@kernel.org>
>> Cc: David Rientjes <rientjes@google.com>
>> Cc: Joonsoo Kim <iamjoonsoo.kim@lge.com>
>> Cc: Andrew Morton <akpm@linux-foundation.org>
>> Cc: Vlastimil Babka <vbabka@suse.cz>
> 
> Anyway the problem and fix seem obvious, so applied. Thanks!

Oops. I should have said something like with 'make W=1' or if
just running scripts/kernel-doc, use -Wall.

Sorry.
-- 
~Randy

Re: [PATCH] mm/slab: fix kernel-doc func param names

[David Rientjes]

On Fri, 10 Jan 2025, Randy Dunlap wrote:

> Use corrected function parameter names to eliminate kernel-doc
> warnings:
> 
> slab.h:142: warning: Function parameter or struct member 's' not described in 'slab_folio'
> slab.h:142: warning: Excess function parameter 'slab' description in 'slab_folio'
> slab.h:168: warning: Function parameter or struct member 's' not described in 'slab_page'
> slab.h:168: warning: Excess function parameter 'slab' description in 'slab_page'
> 
> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
> Cc: Christoph Lameter <cl@linux.com>
> Cc: Pekka Enberg <penberg@kernel.org>
> Cc: David Rientjes <rientjes@google.com>
> Cc: Joonsoo Kim <iamjoonsoo.kim@lge.com>
> Cc: Andrew Morton <akpm@linux-foundation.org>
> Cc: Vlastimil Babka <vbabka@suse.cz>

Acked-by: David Rientjes <rientjes@google.com>

Re: [PATCH] mm/slab: fix kernel-doc func param names

[Vlastimil Babka]

On 1/11/25 21:24, Randy Dunlap wrote:
> Hi,
> 
> On 1/11/25 12:12 PM, Vlastimil Babka wrote:
>> On 1/11/25 07:32, Randy Dunlap wrote:
>>> Use corrected function parameter names to eliminate kernel-doc
>>> warnings:
>>>
>>> slab.h:142: warning: Function parameter or struct member 's' not described in 'slab_folio'
>>> slab.h:142: warning: Excess function parameter 'slab' description in 'slab_folio'
>>> slab.h:168: warning: Function parameter or struct member 's' not described in 'slab_page'
>>> slab.h:168: warning: Excess function parameter 'slab' description in 'slab_page'
>> 
>> I'm unable to get those warnings with "make htmldocs", what exactly do I
>> need to run?
>> 
>>> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
>>> Cc: Christoph Lameter <cl@linux.com>
>>> Cc: Pekka Enberg <penberg@kernel.org>
>>> Cc: David Rientjes <rientjes@google.com>
>>> Cc: Joonsoo Kim <iamjoonsoo.kim@lge.com>
>>> Cc: Andrew Morton <akpm@linux-foundation.org>
>>> Cc: Vlastimil Babka <vbabka@suse.cz>
>> 
>> Anyway the problem and fix seem obvious, so applied. Thanks!
> 
> Oops. I should have said something like with 'make W=1' or if
> just running scripts/kernel-doc, use -Wall.

Thanks, I forgot it's the normal build "make" and not "make htmldocs" (which
I've been attempting with W=1) that will produce the warning. Because slab.h
is likely not listed for inclusions into the htmldocs.

> Sorry.