Hi Markus,
Em Thu, 22 Sep 2016 09:08:50 -0300
Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxx> escreveu:
> Em Tue, 20 Sep 2016 20:56:35 +0200
> Markus Heiser <markus.heiser@xxxxxxxxxxx> 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
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html
