Skip to contentSkip to conversation

mm/slub: drop duplicate kernel-doc for ksize()

PATCH Superseded Sanjay Chitroda 3 participants 6 messages Feb 20 – Feb 24

Subsystems (2)

v1 of 2 Superseded Latest is v2 →

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 mm/slub: drop duplicate kernel-doc for ksize()

From: Sanjay Chitroda <[email protected]>

The ksize() API is already documented in the public header, and Documentation/core-api/mm-api.rst pulls that canonical doc into the book. The kernel-doc block added to mm/slub.c by commit fab0694646d7 ("mm/slab: move [__]ksize and slab_ksize() to mm/slub.c") introduced a second definition for the same symbol in the generated docs, which makes Sphinx emit:

WARNING: Duplicate C declaration, also defined at core-api/mm-api:521 Declaration is '.. c:function:: size_t ksize(const void *objp)'

Remove the redundant kernel-doc comment from slub.c so only the header-provided documentation is emitted. This keeps the user-visible API documentation intact while eliminating the duplicate-declaration warning during make htmldocs.

No functional change.

Fixes fab0694646d7 ("mm/slab: move [__]ksize and slab_ksize() to mm/slub.c")
---
 mm/slub.c | 12 ------------
 1 file changed, 12 deletions(-)
mm/slub.c +0 -12
index 865bc050f654..3f58a485e95e 100644
@@ -6309,18 +6309,6 @@ static size_t __ksize(const void *object)
 	return slab_ksize(slab);
 }
 
-/**
- * ksize -- Report full size of underlying allocation
- * @objp: pointer to the object
- *
- * This should only be used internally to query the true size of allocations.
- * It is not meant to be a way to discover the usable size of an allocation
- * after the fact. Instead, use kmalloc_size_roundup(). Using memory beyond
- * the originally requested allocation size may trigger KASAN, UBSAN_BOUNDS,
- * and/or FORTIFY_SOURCE.
- *
- * Return: size of the actual memory used by @objp in bytes
- */
 size_t ksize(const void *objp)
 {
 	/*
Signature · 1 line
2.34.1
#1 lore raw
Quoted 17 lines · Sanjay Chitroda

From: Sanjay Chitroda <[email protected]>

The ksize() API is already documented in the public header, and Documentation/core-api/mm-api.rst pulls that canonical doc into the book. The kernel-doc block added to mm/slub.c by commit fab0694646d7 ("mm/slab: move [__]ksize and slab_ksize() to mm/slub.c") introduced a second definition for the same symbol in the generated docs, which makes Sphinx emit:

WARNING: Duplicate C declaration, also defined at core-api/mm-api:521 Declaration is '.. c:function:: size_t ksize(const void *objp)'

Remove the redundant kernel-doc comment from slub.c so only the header-provided documentation is emitted. This keeps the user-visible API documentation intact while eliminating the duplicate-declaration warning during make htmldocs.

Quoted 4 lines

No functional change.

Fixes fab0694646d7 ("mm/slab: move [__]ksize and slab_ksize() to mm/slub.c")

The header file kernel-doc looks equivalent without mentioning that it returns bytes. Might be best to make that clear in slab.h?

#2 lore raw
Quoted 2 lines

The header file kernel-doc looks equivalent without mentioning that it returns bytes. Might be best to make that clear in slab.h?

shall we add dedicated change in slab.h to add return bytes information? this would keep this change as clean, what do you suggest?

#3 lore raw
In reply to Sanjay Chitroda
Quoted 11 lines · Sanjay Chitroda

The ksize() API is already documented in the public header, and Documentation/core-api/mm-api.rst pulls that canonical doc into the book. The kernel-doc block added to mm/slub.c by commit fab0694646d7 ("mm/slab: move [__]ksize and slab_ksize() to mm/slub.c") introduced a second definition for the same symbol in the generated docs, which makes Sphinx emit:

WARNING: Duplicate C declaration, also defined at core-api/mm-api:521 Declaration is '.. c:function:: size_t ksize(const void *objp)'

Remove the redundant kernel-doc comment from slub.c so only the

Usually we keep the kernel-doc comment with the implementation, not with the prototype.

#4 lore raw
Quoted 3 lines

Usually we keep the kernel-doc comment with the > implementation, not with the prototype.

I agree with you, Kernel-doc comment should be present with implementation.
I have observed that multiple kernel-doc comments are there in slab.h with prototype, would you suggest to replace all possible at once ?
Or with reference to reported warning; we can keep kernel-doc with implementation and remove from prototype and rectify commit message to highlight ideal kernel-doc practice along with existing commit details so context would be better clear and relavent.

#5 lore raw
In reply to Matthew Wilcox
Quoted 8 lines · Matthew Wilcox
Quoted 7 lines · Sanjay Chitroda

The ksize() API is already documented in the public header, and Documentation/core-api/mm-api.rst pulls that canonical doc into the book. The kernel-doc block added to mm/slub.c by commit fab0694646d7 ("mm/slab: move [__]ksize and slab_ksize() to mm/slub.c") introduced a second definition for the same symbol in the generated docs, which makes Sphinx emit:

Quoted 7 lines
Quoted 4 lines

WARNING: Duplicate C declaration, also defined at core-api/mm-api:521 Declaration is '.. c:function:: size_t ksize(const void *objp)'

Remove the redundant kernel-doc comment from slub.c so only the

Usually we keep the kernel-doc comment with the implementation, not with the prototype.

I agree with you, Kernel-doc comment should be present with implementation.
I have observed that multiple kernel-doc comments are there in slab.h with prototype, would you suggest to replace all possible at once ?

Or with reference to reported warning; we can keep kernel-doc with implementation and remove from prototype and rectify commit message to highlight ideal kernel-doc practice along with existing commit details so context would be better clear and relavent.