why is "const u32 (*tab)[256]" not kerneldoc-able?
when generating the kerneldoc manual kernel-api.html with "make htmldocs", the two routines in lib/crc32.c that refer to a parameter of type "const u32 (*tab)[256]" generate kerneldoc errors: Warning(.//lib/crc32.c:148): No description found for parameter 'tab)[256]' Warning(.//lib/crc32.c:148): Excess function parameter 'tab' description in 'crc32_le_generic' Warning(.//lib/crc32.c:293): No description found for parameter 'tab)[256]' Warning(.//lib/crc32.c:293): Excess function parameter 'tab' description in 'crc32_be_generic' Warning(.//lib/crc32.c): no structured comments found kerneldoc content and declaration for one of them: /** * crc32_le_generic() - Calculate bitwise little-endian Ethernet AUTODIN II * CRC32/CRC32C * @crc: seed value for computation. ~0 for Ethernet, sometimes 0 for other * uses, or the previous crc32/crc32c value if computing incrementally. * @p: pointer to buffer over which CRC32/CRC32C is run * @len: length of buffer @p * @tab: little-endian Ethernet table * @polynomial: CRC32/CRC32c LE polynomial */ static inline u32 __pure crc32_le_generic(u32 crc, unsigned char const *p, size_t len, const u32 (*tab)[256], u32 polynomial) { ... snip ... so what is it about that declaration that causes kerneldoc to choke? and because those two routines are the only kerneldoc content in that source file, the kernel-api page generated for that file is just a dummy page, reporting an error. thoughts? rday -- ======================================================================== Robert P. J. Day Ottawa, Ontario, CANADA http://crashcourse.ca Twitter: http://twitter.com/rpjday LinkedIn: http://ca.linkedin.com/in/rpjday ========================================================================
I believe Kerneldoc starts with just "/*" and not "/**". That looks more like doxygen/ JavaDoc. Have you tried the standard debugging technique of replacing it with a known good comment, and then editing it back to the original until you generate the error, to identify what causes the choking? On 03/02/15 12:19, Robert P. J. Day wrote:
when generating the kerneldoc manual kernel-api.html with "make htmldocs", the two routines in lib/crc32.c that refer to a parameter of type "const u32 (*tab)[256]" generate kerneldoc errors:
Warning(.//lib/crc32.c:148): No description found for parameter 'tab)[256]' Warning(.//lib/crc32.c:148): Excess function parameter 'tab' description in 'crc32_le_generic' Warning(.//lib/crc32.c:293): No description found for parameter 'tab)[256]' Warning(.//lib/crc32.c:293): Excess function parameter 'tab' description in 'crc32_be_generic' Warning(.//lib/crc32.c): no structured comments found
kerneldoc content and declaration for one of them:
/** * crc32_le_generic() - Calculate bitwise little-endian Ethernet AUTODIN II * CRC32/CRC32C * @crc: seed value for computation. ~0 for Ethernet, sometimes 0 for other * uses, or the previous crc32/crc32c value if computing incrementally. * @p: pointer to buffer over which CRC32/CRC32C is run * @len: length of buffer @p * @tab: little-endian Ethernet table * @polynomial: CRC32/CRC32c LE polynomial */ static inline u32 __pure crc32_le_generic(u32 crc, unsigned char const *p, size_t len, const u32 (*tab)[256], u32 polynomial) {
... snip ...
so what is it about that declaration that causes kerneldoc to choke? and because those two routines are the only kerneldoc content in that source file, the kernel-api page generated for that file is just a dummy page, reporting an error.
thoughts?
rday
On Tue, 3 Feb 2015, Malte Vesper wrote:
I believe Kerneldoc starts with just "/*" and not "/**". That looks more like doxygen/ JavaDoc.
no, that is proper kernel-doc, the problem appears to be with parsing that particular declaration. rday -- ======================================================================== Robert P. J. Day Ottawa, Ontario, CANADA http://crashcourse.ca Twitter: http://twitter.com/rpjday LinkedIn: http://ca.linkedin.com/in/rpjday ========================================================================
"Robert P. J. Day" <rpjday@crashcourse.ca> writes:
when generating the kerneldoc manual kernel-api.html with "make htmldocs", the two routines in lib/crc32.c that refer to a parameter of type "const u32 (*tab)[256]" generate kerneldoc errors:
Warning(.//lib/crc32.c:148): No description found for parameter 'tab)[256]' Warning(.//lib/crc32.c:148): Excess function parameter 'tab' description in 'crc32_le_generic' Warning(.//lib/crc32.c:293): No description found for parameter 'tab)[256]' Warning(.//lib/crc32.c:293): Excess function parameter 'tab' description in 'crc32_be_generic' Warning(.//lib/crc32.c): no structured comments found
kerneldoc content and declaration for one of them:
/** * crc32_le_generic() - Calculate bitwise little-endian Ethernet AUTODIN II * CRC32/CRC32C * @crc: seed value for computation. ~0 for Ethernet, sometimes 0 for other * uses, or the previous crc32/crc32c value if computing incrementally. * @p: pointer to buffer over which CRC32/CRC32C is run * @len: length of buffer @p * @tab: little-endian Ethernet table * @polynomial: CRC32/CRC32c LE polynomial */ static inline u32 __pure crc32_le_generic(u32 crc, unsigned char const *p, size_t len, const u32 (*tab)[256], u32 polynomial) {
... snip ...
so what is it about that declaration that causes kerneldoc to choke? and because those two routines are the only kerneldoc content in that source file, the kernel-api page generated for that file is just a dummy page, reporting an error.
thoughts?
Maybe the attached simple patch is good enough? Completely untested except for a single run against that file.... Bjørn
On Tue, 3 Feb 2015, Bjørn Mork wrote:
"Robert P. J. Day" <rpjday@crashcourse.ca> writes:
when generating the kerneldoc manual kernel-api.html with "make htmldocs", the two routines in lib/crc32.c that refer to a parameter of type "const u32 (*tab)[256]" generate kerneldoc errors:
Warning(.//lib/crc32.c:148): No description found for parameter 'tab)[256]' Warning(.//lib/crc32.c:148): Excess function parameter 'tab' description in 'crc32_le_generic' Warning(.//lib/crc32.c:293): No description found for parameter 'tab)[256]' Warning(.//lib/crc32.c:293): Excess function parameter 'tab' description in 'crc32_be_generic' Warning(.//lib/crc32.c): no structured comments found
kerneldoc content and declaration for one of them:
/** * crc32_le_generic() - Calculate bitwise little-endian Ethernet AUTODIN II * CRC32/CRC32C * @crc: seed value for computation. ~0 for Ethernet, sometimes 0 for other * uses, or the previous crc32/crc32c value if computing incrementally. * @p: pointer to buffer over which CRC32/CRC32C is run * @len: length of buffer @p * @tab: little-endian Ethernet table * @polynomial: CRC32/CRC32c LE polynomial */ static inline u32 __pure crc32_le_generic(u32 crc, unsigned char const *p, size_t len, const u32 (*tab)[256], u32 polynomial) {
... snip ...
so what is it about that declaration that causes kerneldoc to choke? and because those two routines are the only kerneldoc content in that source file, the kernel-api page generated for that file is just a dummy page, reporting an error.
thoughts?
Maybe the attached simple patch is good enough? Completely untested except for a single run against that file....
while that patch prevents the error message generation, it still doesn't cause the code to be processed correctly ... if you take a look at the generated kernal-api.html file, in the section on "CRC Functions", the page for that source file is still empty. so your patch will recognize the regular expressions, but it's clear more of the script needs to be fixed to then *generate* the proper output. rday -- ======================================================================== Robert P. J. Day Ottawa, Ontario, CANADA http://crashcourse.ca Twitter: http://twitter.com/rpjday LinkedIn: http://ca.linkedin.com/in/rpjday ========================================================================
Bjørn Mork <bjorn@mork.no> writes:
Maybe the attached simple patch is good enough? Completely untested except for a single run against that file....
Ah, umh, no. That "const u32 (*)[256] tab" does not look correct: crc32_le_generic(9) Kernel Hacker's Manual crc32_le_generic(9) NAME crc32_le_generic - Calculate bitwise little-endian Ethernet AUTODIN II CRC32/CRC32C SYNOPSIS u32 __pure crc32_le_generic (u32 crc, unsigned char const *p, size_t len, const u32 (*)[256] tab, u32 polynomial); ARGUMENTS crc seed value for computation. ~0 for Ethernet, sometimes 0 for other uses, or the previous crc32/crc32c value if computing incrementally. p pointer to buffer over which CRC32/CRC32C is run len length of buffer p tab little-endian Ethernet table polynomial CRC32/CRC32c LE polynomial I guess a proper fix is needed. Bjørn
On Tue, 3 Feb 2015, Bjørn Mork wrote:
Bjørn Mork <bjorn@mork.no> writes:
Maybe the attached simple patch is good enough? Completely untested except for a single run against that file....
Ah, umh, no. That "const u32 (*)[256] tab" does not look correct:
crc32_le_generic(9) Kernel Hacker's Manual crc32_le_generic(9)
NAME crc32_le_generic - Calculate bitwise little-endian Ethernet AUTODIN II CRC32/CRC32C
SYNOPSIS u32 __pure crc32_le_generic (u32 crc, unsigned char const *p, size_t len, const u32 (*)[256] tab, u32 polynomial);
ARGUMENTS crc seed value for computation. ~0 for Ethernet, sometimes 0 for other uses, or the previous crc32/crc32c value if computing incrementally.
p pointer to buffer over which CRC32/CRC32C is run
len length of buffer p
tab little-endian Ethernet table
polynomial CRC32/CRC32c LE polynomial
I guess a proper fix is needed.
actually, i just found where this is a known issue: http://www.spinics.net/lists/linux-doc/msg09364.html rday -- ======================================================================== Robert P. J. Day Ottawa, Ontario, CANADA http://crashcourse.ca Twitter: http://twitter.com/rpjday LinkedIn: http://ca.linkedin.com/in/rpjday ========================================================================
"Robert P. J. Day" <rpjday@crashcourse.ca> writes:
actually, i just found where this is a known issue:
Probably because it's a rare construct. But looking closer at this, trying to understand why the simple test using scripts/kernel-doc lib/crc32.c |man -l - seemed to sort of work, I found that your main problem isn't really the lack of kernel-doc support for array pointer parameters. It's a simple mismatch between the documented and the exported functions. scripts/docproc will only generate docs for exported symbols. lib/crc32.c has no documented *and* exported functions, and thats why the output is empty. The array pointer is a red herring. Bjørn
On Tue, 3 Feb 2015, Bjørn Mork wrote:
"Robert P. J. Day" <rpjday@crashcourse.ca> writes:
actually, i just found where this is a known issue:
Probably because it's a rare construct.
But looking closer at this, trying to understand why the simple test using
scripts/kernel-doc lib/crc32.c |man -l -
seemed to sort of work, I found that your main problem isn't really the lack of kernel-doc support for array pointer parameters. It's a simple mismatch between the documented and the exported functions.
scripts/docproc will only generate docs for exported symbols. lib/crc32.c has no documented *and* exported functions, and thats why the output is empty. The array pointer is a red herring.
ah, good point, i had totally missed that. i'll move this discussion to the linux-doc list and resolve it there. rday -- ======================================================================== Robert P. J. Day Ottawa, Ontario, CANADA http://crashcourse.ca Twitter: http://twitter.com/rpjday LinkedIn: http://ca.linkedin.com/in/rpjday ========================================================================
participants (3)
-
Bjørn Mork -
Malte Vesper -
Robert P. J. Day