why is "const u32 (*tab)[256]" not kerneldoc-able?

why is "const u32 (*tab)[256]" not kerneldoc-able?

[Robert P. J. Day]

  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
========================================================================

why is "const u32 (*tab)[256]" not kerneldoc-able?

[Malte Vesper]

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
>

why is "const u32 (*tab)[256]" not kerneldoc-able?

[Bjørn Mork]

"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

-------------- next part --------------
A non-text attachment was scrubbed...
Name: 0001-kernel-doc-support-pointer-to-array-params.patch
Type: text/x-diff
Size: 1010 bytes
Desc: not available
Url : http://lists.kernelnewbies.org/pipermail/kernelnewbies/attachments/20150203/36e77b6f/attachment-0001.bin 

why is "const u32 (*tab)[256]" not kerneldoc-able?

[Robert P. J. Day]

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
========================================================================

why is "const u32 (*tab)[256]" not kerneldoc-able?

[Bjørn Mork]

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

why is "const u32 (*tab)[256]" not kerneldoc-able?

[Robert P. J. Day]

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
========================================================================

why is "const u32 (*tab)[256]" not kerneldoc-able?

[Robert P. J. Day]

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
========================================================================

why is "const u32 (*tab)[256]" not kerneldoc-able?

[Bjørn Mork]

"Robert P. J. Day" <rpjday@crashcourse.ca> writes:

>   actually, i just found where this is a known issue:
>
> http://www.spinics.net/lists/linux-doc/msg09364.html

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

why is "const u32 (*tab)[256]" not kerneldoc-able?

[Robert P. J. Day]

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:
> >
> > http://www.spinics.net/lists/linux-doc/msg09364.html
>
> 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
========================================================================