Re: [PATCH 12/36] tty: tty_io: Fix some kernel-doc issues

[Lee Jones <lee.jones@linaro.org>]

On Thu, 05 Nov 2020, Jiri Slaby wrote:

> On 04. 11. 20, 20:35, Lee Jones wrote:
> > Demote non-conformant headers and supply some missing descriptions.
> > 
> > Fixes the following W=1 kernel build warning(s):
> > 
> >   drivers/tty/tty_io.c:218: warning: Function parameter or member 'file' not described in 'tty_free_file'
> >   drivers/tty/tty_io.c:566: warning: Function parameter or member 'exit_session' not described in '__tty_hangup'
> >   drivers/tty/tty_io.c:1077: warning: Function parameter or member 'tty' not described in 'tty_send_xchar'
> >   drivers/tty/tty_io.c:1077: warning: Function parameter or member 'ch' not described in 'tty_send_xchar'
> >   drivers/tty/tty_io.c:1155: warning: Function parameter or member 'file' not described in 'tty_driver_lookup_tty'
> >   drivers/tty/tty_io.c:1508: warning: Function parameter or member 'tty' not described in 'release_tty'
> >   drivers/tty/tty_io.c:1508: warning: Function parameter or member 'idx' not described in 'release_tty'
> >   drivers/tty/tty_io.c:2973: warning: Function parameter or member 'driver' not described in 'alloc_tty_struct'
> >   drivers/tty/tty_io.c:2973: warning: Function parameter or member 'idx' not described in 'alloc_tty_struct'
> > 
> > Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
> > Cc: Jiri Slaby <jirislaby@kernel.org>
> > Cc: Nick Holloway <alfie@dcs.warwick.ac.uk>
> > Cc: -- <julian@uhunix.uhcc.hawaii.edu>
> > Cc: Marko Kohtala <Marko.Kohtala@hut.fi>
> > Cc: Bill Hawes <whawes@star.net>
> > Cc: "C. Scott Ananian" <cananian@alumni.princeton.edu>
> > Cc: Russell King <rmk@arm.linux.org.uk>
> > Cc: Andrew Morton <andrewm@uow.edu.eu>
> > Signed-off-by: Lee Jones <lee.jones@linaro.org>
> > ---
> >   drivers/tty/tty_io.c | 10 +++++++---
> >   1 file changed, 7 insertions(+), 3 deletions(-)
> > 
> > diff --git a/drivers/tty/tty_io.c b/drivers/tty/tty_io.c
> > index 88b00c47b606e..f50286fb080da 100644
> > --- a/drivers/tty/tty_io.c
> > +++ b/drivers/tty/tty_io.c
> > @@ -2961,7 +2965,7 @@ static struct device *tty_get_device(struct tty_struct *tty)
> >   }
> > -/**
> > +/*
> >    *	alloc_tty_struct
> >    *
> >    *	This subroutine allocates and initializes a tty structure.
> 
> Why do you randomly sometimes fix kernel-doc and sometimes remove functions
> from kernel-doc? What's the rule?

The decision is made quickly (I am fixing literally 1000's of these),
but the process is definitely not random.

If there has been little or no attempt to document the function, it
gets demoted.  If the developer has had a good crack at providing
descriptions and/or the header is just suffering with a little
incompleteness/doc-rot, then I'll fix it up.

Here for example, no attempt was made to provide any proper
documentation.

> For example, alloc_tty_struct is among the
> ones, I would like to see fixed instead of removed from kernel-doc.

There is nothing stopping anyone from providing said descriptions and
promoting it back up to kernel-doc.  If you have good reasons for it
to be properly documented with kernel-doc, then it should also be
referenced from /Documentation using the kernel-doc:: notation.

Also see: scripts/find-unused-docs.sh

-- 
Lee Jones [李琼斯]
Senior Technical Lead - Developer Services
Linaro.org │ Open source software for Arm SoCs
Follow Linaro: Facebook | Twitter | Blog