Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.35 as permitted sender) client-ip=23.128.96.35;
Date:   Tue, 19 Sep 2023 13:51:32 +0300 (EEST)
From:   =?ISO-8859-15?Q?Ilpo_J=E4rvinen?= <ilpo.jarvinen@linux.intel.com>
To:     Jiri Slaby <jirislaby@kernel.org>
cc:     Greg Kroah-Hartman <gregkh@linuxfoundation.org>,
        linux-serial <linux-serial@vger.kernel.org>,
        LKML <linux-kernel@vger.kernel.org>
Subject: Re: [PATCH 09/15] tty: fix kernel-doc for functions in tty.h
In-Reply-To: <6d06e531-6c69-47ca-9832-fac21ce6964c@kernel.org>
Message-ID: <576ae74-19dc-84b5-7e8c-563c9561be5d@linux.intel.com>
References: <20230919085156.1578-1-jirislaby@kernel.org> <20230919085156.1578-10-jirislaby@kernel.org> <6033668f-71cc-b21-a034-a1ff31d7279@linux.intel.com> <ae486636-c075-41d9-9304-b0cfb07c132c@kernel.org> <6d06e531-6c69-47ca-9832-fac21ce6964c@kernel.org>
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="8323329-2030825116-1695120695=:1920"
Precedence: bulk

  This message is in MIME format.  The first part should be readable text,
  while the remaining parts are likely unreadable without MIME-aware tools.

--8323329-2030825116-1695120695=:1920
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8BIT

On Tue, 19 Sep 2023, Jiri Slaby wrote:

> On 19. 09. 23, 12:45, Jiri Slaby wrote:
> > 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@kernel.org>
> > > > ---
> > > >   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.
> 
> Ah, no. The Locking Alan introduced means what _this_ function locks. I am not
> sure we want to extend the meaning to _expected_ locks?

There are plenty of examples with "Must be called with" or "Caller holds"
in Locking. This is for humans anyway so one reading should understand it.


-- 
 i.

--8323329-2030825116-1695120695=:1920--