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

[Ilpo Järvinen]

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?

>   */
> -
>  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.