kernel-lintdoc parser - was: Re: [PATCH v2 0/3] doc-rst:c-domain: fix some issues in the c-domain

[Mauro Carvalho Chehab <mchehab@infradead.org>]

Hi Markus,

Em Thu, 22 Sep 2016 09:08:50 -0300
Mauro Carvalho Chehab <mchehab@infradead.org> escreveu:

> Em Tue, 20 Sep 2016 20:56:35 +0200
> Markus Heiser <markus.heiser@darmarit.de> escreveu:
> 

> The new parser seems to have some bugs, like those:
> 
> $ kernel-lintdoc include/media/v4l2-ctrls.h
> include/media/v4l2-ctrls.h:106 :WARN: typedef of function pointer not marked as typdef, use: 'typedef v4l2_ctrl_notify_fnc' in the comment.
> ...
> include/media/v4l2-ctrls.h:605 :WARN: typedef of function pointer not marked as typdef, use: 'typedef v4l2_ctrl_filter' in the comment.
> ...
> include/media/v4l2-ctrls.h:809 [kernel-doc WARN] : can't understand function proto: 'const char * const *v4l2_ctrl_get_menu(u32 id);'
> ...

I ran the kernel-lintdoc with:
	for i in $(git grep kernel-doc Documentation/media/kapi/|cut -d: -f4); do kernel-lintdoc --sloppy $i; done

and I have a few comments:

1) instead of printing the full patch, it would be good to print the
relative patch, as this makes easier to paste the errors on e-mails
and on patches.

2) Parsing of embedded structs/unions

On some headers like dvb_frontend.h, we have unamed structs and enums
inside structs:

struct dtv_frontend_properties {
...
	struct {
	    u8			segment_count;
	    enum fe_code_rate	fec;
	    enum fe_modulation	modulation;
	    u8			interleaving;
	} layer[3];
...
};

The fields of the embedded struct are described as:

 * @layer:		ISDB per-layer data (only ISDB standard)
 * @layer.segment_count: Segment Count;
 * @layer.fec:		per layer code rate;
 * @layer.modulation:	per layer modulation;
 * @layer.interleaving:	 per layer interleaving.

kernel-lintdoc didn't like that:

	drivers/media/dvb-core/dvb_frontend.h:513 :ERROR: duplicate parameter definition 'layer'
	drivers/media/dvb-core/dvb_frontend.h:514 :ERROR: duplicate parameter definition 'layer'
	drivers/media/dvb-core/dvb_frontend.h:515 :ERROR: duplicate parameter definition 'layer'
	drivers/media/dvb-core/dvb_frontend.h:516 :ERROR: duplicate parameter definition 'layer'

2) it complains about function typedefs:

	drivers/media/dvb-core/demux.h:251 :WARN: typedef of function pointer not marked as typdef, use: 'typedef dmx_ts_cb' in the comment.
	drivers/media/dvb-core/demux.h:292 :WARN: typedef of function pointer not marked as typdef, use: 'typedef dmx_section_cb' in the comment.
	include/media/v4l2-ioctl.h:677 :WARN: typedef of function pointer not marked as typdef, use: 'typedef v4l2_kioctl' in the comment.
	include/media/v4l2-ctrls.h:106 :WARN: typedef of function pointer not marked as typdef, use: 'typedef v4l2_ctrl_notify_fnc' in the comment.
	include/media/v4l2-ctrls.h:606 :WARN: typedef of function pointer not marked as typdef, use: 'typedef v4l2_ctrl_filter' in the comment.
	include/media/v4l2-dv-timings.h:39 :WARN: typedef of function pointer not marked as typdef, use: 'typedef v4l2_check_dv_timings_fnc' in the comment.
	include/media/v4l2-dv-timings.h:39 :WARN: typedef of function pointer used uncommon code style: 'typedef bool v4l2_check_dv_timings_fnc(const struct v4l2_dv_timings *t, void *handle);'
	include/media/videobuf2-core.h:877 :WARN: typedef of function pointer not marked as typdef, use: 'typedef vb2_thread_fnc' in the comment.

3) this is actually a more complex problem: how to represent returned values
from the function callbacks. Maybe we'll need to patch kernel-doc. Right now,
it complains with:

	drivers/media/dvb-core/demux.h:397 :WARN: duplicate section name 'It returns'
	drivers/media/dvb-core/demux.h:415 :WARN: duplicate section name 'It returns'
	drivers/media/dvb-core/demux.h:431 :WARN: duplicate section name 'It returns'
	drivers/media/dvb-core/demux.h:444 :WARN: duplicate section name 'It returns'
	drivers/media/dvb-core/demux.h:462 :WARN: duplicate section name 'It returns'
	drivers/media/dvb-core/demux.h:475 :WARN: duplicate section name 'It returns'
	drivers/media/dvb-core/demux.h:491 :WARN: duplicate section name 'It returns'
	drivers/media/dvb-core/demux.h:507 :WARN: duplicate section name 'It returns'
	drivers/media/dvb-core/demux.h:534 :WARN: duplicate section name 'It returns'
	drivers/media/dvb-core/demux.h:542 :WARN: duplicate section name 'It returns'
	drivers/media/dvb-core/demux.h:552 :WARN: duplicate section name 'It returns'

4) Parse errors.

Those seem to be caused by some errors at the parser:

	include/media/v4l2-ctrls.h:809 :WARN: can't understand function proto: 'const char * const *v4l2_ctrl_get_menu(u32 id);'
	include/media/v4l2-dev.h:173 :WARN: no description found for parameter 'valid_ioctls\[BITS_TO_LONGS(BASE_VIDIOC_PRIVATE)\]'
	include/media/v4l2-dev.h:173 :WARN: no description found for parameter 'disable_locking\[BITS_TO_LONGS(BASE_VIDIOC_PRIVATE)\]'
	include/media/videobuf2-core.h:555 :ERROR: can't parse struct!


Thanks,
Mauro