Re: [Ksummit-discuss] [TECH TOPIC] Documentation

On Sat, 2020-06-13 at 18:42 +0200, Julia Lawall wrote:
> I tried collecting information about missing or incorrectly formatted
> function documentation using Coccinelle.  Here is an example of the
> output:
> 
> drivers/net/ethernet/freescale/fman/fman.c:2077 fman_register_intr: extra names mod, f_isr, h_src_arg
> drivers/net/ethernet/freescale/fman/fman.c:2077 fman_register_intr: missing name isr_cb
> drivers/net/ethernet/freescale/fman/fman.c:2077 fman_register_intr: missing name module
> drivers/net/ethernet/freescale/fman/fman.c:2077 fman_register_intr: missing name src_arg
> drivers/net/ethernet/freescale/fman/fman.c:2077 fman_register_intr: return comment but no return value
> drivers/net/ethernet/freescale/fman/fman.c:2103 fman_unregister_intr: extra names mod
> drivers/net/ethernet/freescale/fman/fman.c:2103 fman_unregister_intr: missing name module
> drivers/net/ethernet/freescale/fman/fman.c:2103 fman_unregister_intr: return comment but no return value
> drivers/net/ethernet/freescale/fman/fman.c:2355 fman_get_revision: return comment but no return value
> drivers/net/ethernet/freescale/fman/fman.c:2520 fman_bind: extra names dev
> drivers/net/ethernet/freescale/fman/fman.c:2520 fman_bind: missing name fm_dev
> drivers/net/ethernet/freescale/fman/fman.c:2527 fman_has_errata_a050385: no comment for fman_has_errata_a050385

just fyi: scripts/kernel-doc already does:

$ ./scripts/kernel-doc drivers/net/ethernet/freescale/fman/fman.c > /dev/null
drivers/net/ethernet/freescale/fman/fman.c:2080: warning: Function parameter or member 'module' not described in 'fman_register_intr'
drivers/net/ethernet/freescale/fman/fman.c:2080: warning: Function parameter or member 'isr_cb' not described in 'fman_register_intr'
drivers/net/ethernet/freescale/fman/fman.c:2080: warning: Function parameter or member 'src_arg' not described in 'fman_register_intr'
drivers/net/ethernet/freescale/fman/fman.c:2080: warning: Excess function parameter 'mod' description in 'fman_register_intr'
drivers/net/ethernet/freescale/fman/fman.c:2080: warning: Excess function parameter 'f_isr' description in 'fman_register_intr'
drivers/net/ethernet/freescale/fman/fman.c:2080: warning: Excess function parameter 'h_src_arg' description in 'fman_register_intr'
drivers/net/ethernet/freescale/fman/fman.c:2105: warning: Function parameter or member 'module' not described in 'fman_unregister_intr'
drivers/net/ethernet/freescale/fman/fman.c:2105: warning: Excess function parameter 'mod' description in 'fman_unregister_intr'
drivers/net/ethernet/freescale/fman/fman.c:2356: warning: Function parameter or member 'fman' not described in 'fman_get_revision'
drivers/net/ethernet/freescale/fman/fman.c:2356: warning: Function parameter or member 'rev_info' not described in 'fman_get_revision'
drivers/net/ethernet/freescale/fman/fman.c:2521: warning: Function parameter or member 'fm_dev' not described in 'fman_bind'
drivers/net/ethernet/freescale/fman/fman.c:2521: warning: Excess function parameter 'dev' description in 'fman_bind'



_______________________________________________
Ksummit-discuss mailing list
[email protected]
https://lists.linuxfoundation.org/mailman/listinfo/ksummit-discuss