Aditya <yashsri421@xxxxxxxxx> 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 = {
.midle_shift = SYSC_TYPE2_MIDLEMODE_SHIFT,
.sidle_shift = SYSC_TYPE2_SIDLEMODE_SHIFT,
.srst_shift = SYSC_TYPE2_SOFTRESET_SHIFT,
.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
s%/**%/*%
> 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.
Thanks,
jon
