Re: [PATCH 09/15] tty: fix kernel-doc for functions in tty.h

[Jiri Slaby]

On 19. 09. 23, 12:07, Ilpo Järvinen wrote:
> On Tue, 19 Sep 2023, Jiri Slaby (SUSE) wrote:
>
> > tty_kref_get() is already included in Documentation, but is not properly
> > formatted. Fix this.
> >
> > tty_get_baud_rate() is neither properly formatted, nor is included. Fix
> > both.
> >
> > Signed-off-by: Jiri Slaby (SUSE) <jirislaby@xxxxxxxxxx>
> > ---
> >   Documentation/driver-api/tty/tty_ioctl.rst |  3 +++
> >   include/linux/tty.h                        | 21 +++++++++------------
> >   2 files changed, 12 insertions(+), 12 deletions(-)
> >
> > diff --git a/Documentation/driver-api/tty/tty_ioctl.rst b/Documentation/driver-api/tty/tty_ioctl.rst
> > index 9b0be79fc15e..3ff1ac5e07f1 100644
> > --- a/Documentation/driver-api/tty/tty_ioctl.rst
> > +++ b/Documentation/driver-api/tty/tty_ioctl.rst
> > @@ -5,3 +5,6 @@ TTY IOCTL Helpers
> >   =================
> >   
> >   .. kernel-doc:: drivers/tty/tty_ioctl.c
> > +
> > +.. kernel-doc:: include/linux/tty.h
> > +   :identifiers: tty_get_baud_rate
> > diff --git a/include/linux/tty.h b/include/linux/tty.h
> > index 59d675f345e9..4b6340ac2af2 100644
> > --- a/include/linux/tty.h
> > +++ b/include/linux/tty.h
> > @@ -390,14 +390,12 @@ int vcs_init(void);
> >   extern const struct class tty_class;
> >   
> >   /**
> > - *	tty_kref_get		-	get a tty reference
> > - *	@tty: tty device
> > + * tty_kref_get - get a tty reference
> > + * @tty: tty device
> >    *
> > - *	Return a new reference to a tty object. The caller must hold
> > - *	sufficient locks/counts to ensure that their existing reference cannot
> > - *	go away
> > + * Returns: a new reference to a tty object. The caller must hold sufficient
> > + * locks/counts to ensure that their existing reference cannot go away
>
> Shouldn't this have also Locking: entry instead of hiding the details into
> Return?

/me left to fix both in a separate patch.

thanks,
--
js
suse labs