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

On Sun, Jun 14, 2020 at 09:23:41AM -0400, Matthew Wilcox wrote:
> Also W=1 will enable documentation warnings. We can move that to default if we
> want people to take documentation seriously. Last time I tried it added about
> 700 warnings to the build and I didn't have the spoons to make a serious dent
> in fixing those warnings.
> 
> Maybe _that_ would be a good beginner task because it doesn't take much in
> depth knowledge of any particular subsystem.

That's true, but unless we pay more attention to include kerneldoc
changes with patches that change APIs we would train many beginners this
way ;-)

> On Sat., Jun. 13, 2020, 12:57 Joe Perches, <[email protected]> wrote:
> 
>     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
> 

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


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