2023-09-19 08:57:26

by Jiri Slaby

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

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) <[email protected]>
---
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
*/
-
static inline struct tty_struct *tty_kref_get(struct tty_struct *tty)
{
if (tty)
@@ -435,14 +433,13 @@ void tty_encode_baud_rate(struct tty_struct *tty, speed_t ibaud,
speed_t obaud);

/**
- * tty_get_baud_rate - get tty bit rates
- * @tty: tty to query
+ * tty_get_baud_rate - get tty bit rates
+ * @tty: tty to query
*
- * Returns the baud rate as an integer for this terminal. The
- * termios lock must be held by the caller and the terminal bit
- * flags may be updated.
+ * Returns: the baud rate as an integer for this terminal. The termios lock
+ * must be held by the caller and the terminal bit flags may be updated.
*
- * Locking: none
+ * Locking: none
*/
static inline speed_t tty_get_baud_rate(struct tty_struct *tty)
{
--
2.42.0

2023-09-19 11:03:05

by Ilpo Järvinen

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

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) <[email protected]>
> > > > ---
> > > >   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.

2023-09-19 11:09:10

by Jiri Slaby

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

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) <[email protected]>
>>> ---
>>>   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?

thanks,
--
js
suse labs

2023-09-19 11:20:01

by Jiri Slaby

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

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) <[email protected]>
>> ---
>> 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

2023-09-19 21:03:05

by Ilpo Järvinen

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

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) <[email protected]>
> ---
> 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?

> */
> -
> static inline struct tty_struct *tty_kref_get(struct tty_struct *tty)
> {
> if (tty)
> @@ -435,14 +433,13 @@ void tty_encode_baud_rate(struct tty_struct *tty, speed_t ibaud,
> speed_t obaud);
>
> /**
> - * tty_get_baud_rate - get tty bit rates
> - * @tty: tty to query
> + * tty_get_baud_rate - get tty bit rates
> + * @tty: tty to query
> *
> - * Returns the baud rate as an integer for this terminal. The
> - * termios lock must be held by the caller and the terminal bit
> - * flags may be updated.
> + * Returns: the baud rate as an integer for this terminal. The termios lock
> + * must be held by the caller and the terminal bit flags may be updated.
> *
> - * Locking: none
> + * Locking: none

Eh, the paragraph above says, "The termios lock must be held by the
caller" so this "Locking: none" seems pretty bogus.

> */
> static inline speed_t tty_get_baud_rate(struct tty_struct *tty)
> {
>

--
i.