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