[Linux-kernel-mentees] Investigating parsing error for struct/union

Jonathan Corbet corbet at lwn.net
Mon Feb 22 21:56:58 UTC 2021

Aditya <yashsri421 at gmail.com> writes:

> 1) A large part of this error(~80%) occurs due to the presence of one
> or more lines(such as '#define' lines) between commented code and
> struct declaration.

See my other email for this one.

> 2) If struct does not contain any members, for e.g., in
> include/linux/xz.h:
> /**
>  * struct xz_dec - Opaque type to hold the XZ decoder state
>  */
> struct xz_dec;
> Here, it causes error as the curly braces and members expected by the
> regex, are absent.

Here, too, the real problem is that the kerneldoc comment is in the
wrong place.  There will be a real declaration for that structure
somewhere; in this case it's lib/xz/xz_dec_stream.c.  *That* is where
the kerneldoc comment should be.

That said, the above isn't a kerneldoc comment anyway; it doesn't really
describe anything useful and would generate lots of warnings if it were
in the right place.  The right solution is either (1) write a proper
comment describing this structure, or (2) delete the extra "*" at the
beginning of this comment.

> 3) Different Syntax than expected. For e.g.:
>     a) struct xyz struct_name {} syntax. This syntax has been used in
> arch/arm/mach-omap2/omap_hwmod_common_data.c file

*Please* give an actual example, from the source, of what you are
talking about for cases like this; I spent a while looking at that file
trying to figure out what you were talking about.  I assume you're
referring to silliness like this:

 * struct omap_hwmod_sysc_type2 - TYPE2 sysconfig scheme.
 * To be used by hwmod structure to specify the sysconfig offsets if the
 * device ip is compliant with the new PRCM protocol defined for new
 * OMAP4 IPs.
struct sysc_regbits omap_hwmod_sysc_type2 = {
	.dmadisable_shift = SYSC_TYPE2_DMADISABLE_SHIFT,

...right?  Again, the problem here is that these are not proper
kerneldoc comments.  We're not describing the structure, this is just a
comment describing a specific variable.  The right fix, once again, is

>     b) "static __maybe_unused const struct st_sensors_platform_data
> default_press_pdata = {" in drivers/iio/pressure/st_pressure.h.
> This kind of syntax has also been used in
> drivers/iio/accel/st_accel.h, and drivers/iio/gyro/st_gyro.h

Same problem here; the fix is not in the docs build system.



More information about the Linux-kernel-mentees mailing list