mm/slub: drop duplicate kernel-doc for ksize()
Subsystems (2)
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.
--- mm/slub.c | 12 ------------ 1 file changed, 12 deletions(-)
mm/slub.c +0 -12
@@ -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
David Rientjes
reviewerQuoted 17 lines · Sanjay Chitroda
From: Sanjay Chitroda <[email protected]>
The
ksize()API is already documented in the public header, andDocumentation/core-api/mm-api.rstpulls that canonical doc into the book. The kernel-doc block added tomm/slub.cby commitfab0694646d7("mm/slab: move [__]ksize andslab_ksize()tomm/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_tksize(const void *objp)'Remove the redundant kernel-doc comment from
slub.cso only the header-provided documentation is emitted. This keeps the user-visible API documentation intact while eliminating the duplicate-declaration warning duringmake htmldocs.
Quoted 4 lines
No functional change.
Fixes fab0694646d7 ("mm/slab: move [__]ksize and slab_ksize() to mm/slub.c")Signed-off-by Sanjay Chitroda <[email protected]>
The header file kernel-doc looks equivalent without mentioning that it returns bytes. Might be best to make that clear in slab.h?
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?
Quoted 11 lines · Sanjay Chitroda
The
ksize()API is already documented in the public header, andDocumentation/core-api/mm-api.rstpulls that canonical doc into the book. The kernel-doc block added tomm/slub.cby commitfab0694646d7("mm/slab: move [__]ksize andslab_ksize()tomm/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_tksize(const void *objp)'Remove the redundant kernel-doc comment from
slub.cso only the
Usually we keep the kernel-doc comment with the implementation, not with the prototype.
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.
Quoted 8 lines · Matthew Wilcox
Quoted 7 lines · Sanjay Chitroda
The
ksize()API is already documented in the public header, andDocumentation/core-api/mm-api.rstpulls that canonical doc into the book. The kernel-doc block added tomm/slub.cby commitfab0694646d7("mm/slab: move [__]ksize andslab_ksize()tomm/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_tksize(const void *objp)'Remove the redundant kernel-doc comment from
slub.cso only theUsually 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.