Re: [PATCH v2 1/1] tty: n_tty: Fix some misdocumented functions

[Jiri Slaby]

On 27. 05. 21, 10:20, Lee Jones wrote:
> On Thu, 27 May 2021, Jiri Slaby wrote:
>
> > On 26. 05. 21, 10:31, Lee Jones wrote:
> > > Fixes the following W=1 kernel build warning(s):
> > >
> > >    drivers/tty/n_tty.c:623: warning: expecting prototype for process_echoes(). Prototype was for __process_echoes() instead
> > >    drivers/tty/n_tty.c:1109: warning: expecting prototype for isig(). Prototype was for __isig() instead
> > >    drivers/tty/n_tty.c:1268: warning: expecting prototype for n_tty_receive_char(). Prototype was for n_tty_receive_char_special() instead
> > >    drivers/tty/n_tty.c:2132: warning: Excess function parameter 'buf' description in 'n_tty_read'
> > >
> > > Cc: Greg Kroah-Hartman <gregkh@xxxxxxxxxxxxxxxxxxx>
> > > Cc: Jiri Slaby <jirislaby@xxxxxxxxxx>
> > > Cc: "Andrew J. Kroll" <ag784@xxxxxxxxxxxxxxxxxxx>
> > > Cc: processes-Sapan Bhatia <sapan@xxxxxxxxxxxx>
> > > Signed-off-by: Lee Jones <lee.jones@xxxxxxxxxx>
> > > ---
> > >
> > > v2: Rebased
> > >
> > >    drivers/tty/n_tty.c | 10 +++++-----
> > >    1 file changed, 5 insertions(+), 5 deletions(-)
> > >
> > > diff --git a/drivers/tty/n_tty.c b/drivers/tty/n_tty.c
> > > index 0ec93f1a61f5d..56d3b43d8a3a4 100644
> > > --- a/drivers/tty/n_tty.c
> > > +++ b/drivers/tty/n_tty.c
> > ...
> > > @@ -1248,7 +1248,7 @@ n_tty_receive_signal_char(struct tty_struct *tty, int signal, unsigned char c)
> > >    }
> > >    /**
> > > - *	n_tty_receive_char	-	perform processing
> > > + *	n_tty_receive_char_special	-	perform processing
> >
> > No, please move the doc to the function in this case instead.
>
> Oh, so this *really* is the doc for n_tty_receive_char()?

Yes, it is supposed to. See 4b1f79c2d7352605b567cab49de20d3b67762ee3, 
which omitted to move the comment.

> > >     *	@tty: terminal device
> > >     *	@c: character
> > >     *
> > > @@ -2042,11 +2042,11 @@ static int job_control(struct tty_struct *tty, struct file *file)
> > >    }
> > > -/**
> > > +/*
> >
> > Why this?
>
> Because the author has missed:
>
>    void **cookie, unsigned long offset

Oh, that. The doc by far predates the recent cookie introduction.

> Once these descriptions are provided, it can be re-promoted.

OK, I will fix this later. I am just putting the pieces together to link 
all these TTY kernel-docs from Documentation/.

thanks,
--
js
suse labs