From 3b1a696bb96882d4f85c7cca07383d94cb7c2de3 Mon Sep 17 00:00:00 2001 From: "Jiri Slaby (SUSE)" Date: Tue, 19 Sep 2023 10:51:49 +0200 Subject: tty: fix up and plug in tty_ioctl kernel-doc The ioctl helpers are well documented, except they are not plugged in the Documentation. So fix up the minor issues in the kernel-doc and plug it in. The minor issues include: * bad \t on every line (sphinx misinterprets the description otherwise) * missing colon after Return * superfluous \n after the comment * make some struct members and constants a hyperlink * and so on Perhaps better to use --word-diff if one wants to see the "real" changes. Signed-off-by: "Jiri Slaby (SUSE)" Link: https://lore.kernel.org/r/20230919085156.1578-9-jirislaby@kernel.org Signed-off-by: Greg Kroah-Hartman --- Documentation/driver-api/tty/index.rst | 1 + Documentation/driver-api/tty/tty_ioctl.rst | 7 +++++++ 2 files changed, 8 insertions(+) create mode 100644 Documentation/driver-api/tty/tty_ioctl.rst (limited to 'Documentation/driver-api') diff --git a/Documentation/driver-api/tty/index.rst b/Documentation/driver-api/tty/index.rst index 2d32606a4278..b490da11f257 100644 --- a/Documentation/driver-api/tty/index.rst +++ b/Documentation/driver-api/tty/index.rst @@ -36,6 +36,7 @@ In-detail description of the named TTY structures is in separate documents: tty_struct tty_ldisc tty_buffer + tty_ioctl tty_internals Writing TTY Driver diff --git a/Documentation/driver-api/tty/tty_ioctl.rst b/Documentation/driver-api/tty/tty_ioctl.rst new file mode 100644 index 000000000000..9b0be79fc15e --- /dev/null +++ b/Documentation/driver-api/tty/tty_ioctl.rst @@ -0,0 +1,7 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================= +TTY IOCTL Helpers +================= + +.. kernel-doc:: drivers/tty/tty_ioctl.c -- cgit v1.2.3 From 71067fb797e074c468221793fe93ba1b58350f1e Mon Sep 17 00:00:00 2001 From: "Jiri Slaby (SUSE)" Date: Tue, 19 Sep 2023 10:51:50 +0200 Subject: 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)" Link: https://lore.kernel.org/r/20230919085156.1578-10-jirislaby@kernel.org Signed-off-by: Greg Kroah-Hartman --- Documentation/driver-api/tty/tty_ioctl.rst | 3 +++ include/linux/tty.h | 21 +++++++++------------ 2 files changed, 12 insertions(+), 12 deletions(-) (limited to 'Documentation/driver-api') 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) { -- cgit v1.2.3