linux-kernel - [PATCH] docs/driver-api/miscellaneous: Remove kernel-doc of serial

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [thread-next>] [day] [month] [year] [list]

Message-ID: <4e54c76a-138a-07e0-985a-dd83cb622208@gmail.com>
Date:   Wed, 2 Nov 2022 20:48:01 +0900
From:   Akira Yokosawa <akiyks@...il.com>
To:     Jiri Slaby <jslaby@...e.cz>,
        Greg Kroah-Hartman <gregkh@...uxfoundation.org>,
        Jonathan Corbet <corbet@....net>
Cc:     Akira Yokosawa <akiyks@...il.com>, linux-doc@...r.kernel.org,
        linux-kernel@...r.kernel.org
Subject: [PATCH] docs/driver-api/miscellaneous: Remove kernel-doc of
 serial_core.c

Since merge of tty-6.0-rc1, "make htmldocs" with Sphinx >=3.1 emits
a bunch of warnings indicating duplicate kernel-doc comments from
drivers/tty/serial/serial_core.c.

This is due to the kernel-doc directive for serial_core.c in
serial/drivers.rst added in the merge. It conflicts with an existing
kernel-doc directive in miscellaneous.rst.

Remove the latter directive and resolve the duplicates.

Signed-off-by: Akira Yokosawa <akiyks@...il.com>
Fixes: 607ca0f742b7 ("Merge tag 'tty-6.0-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/tty")
Cc: stable@...r.kernel.org # 6.0
Cc: Jiri Slaby <jslaby@...e.cz>
Cc: Greg Kroah-Hartman <gregkh@...uxfoundation.org>
---
Hi Jiri,

I've seeing the increased warnings of duplicates from "make htmldocs"
since the 6.0 merge window. They look like (partial):

/linux/Documentation/driver-api/serial/driver.rst:111: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous:111.
Declaration is '.. c:function:: void uart_write_wakeup(struct uart_port *port)'.
/linux/Documentation/driver-api/serial/driver.rst:111: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous:111.
Declaration is '.. c:None:: struct uart_port *port'.
/linux/Documentation/driver-api/serial/driver.rst:343: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous:343.
Declaration is '.. c:function:: void uart_update_timeout(struct uart_port *port, unsigned int cflag, unsigned int baud)'.
/linux/Documentation/driver-api/serial/driver.rst:343: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous:343.
Declaration is '.. c:None:: struct uart_port *port'.
/linux/Documentation/driver-api/serial/driver.rst:343: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous:343.
Declaration is '.. c:None:: unsigned int cflag'.
/linux/Documentation/driver-api/serial/driver.rst:343: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous:343.
Declaration is '.. c:None:: unsigned int baud'.
/linux/Documentation/driver-api/serial/driver.rst:376: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous:376.

These warning messages are not easy to track down, as there is an
unresolved issue in Sphinx's C domain parser who can't handle a
function and a struct of the same name and causes duplicates in a
later stage of Sphinx processing.

But the warnings shown above turned out to be true duplicates.

There is a not-clearly-documented rule in including kernel-doc
comments into .rst files. Any kernel-doc comment can be included
at most once in the whole documentation tree. Otherwise, you can't
be sure of which target a cross-reference points to.

As I don't have full context of these kernel-doc comments, this is
meant as a band-aide patch, especially the reference to
serial/driver.rst added at the bottom.

If I can get acks from you and/or Greg, I'd like Jon to take the
fix, as this issue affects the -doc tree most.

Thanks,
Akira

--
 Documentation/driver-api/miscellaneous.rst | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/Documentation/driver-api/miscellaneous.rst b/Documentation/driver-api/miscellaneous.rst
index 304ffb146cf9..4a5104a368ac 100644
--- a/Documentation/driver-api/miscellaneous.rst
+++ b/Documentation/driver-api/miscellaneous.rst
@@ -16,12 +16,11 @@ Parallel Port Devices
 16x50 UART Driver
 =================

-.. kernel-doc:: drivers/tty/serial/serial_core.c
-   :export:
-
 .. kernel-doc:: drivers/tty/serial/8250/8250_core.c
    :export:

+See serial/driver.rst for related APIs.
+
 Pulse-Width Modulation (PWM)
 ============================

base-commit: 30a0b95b1335e12efef89dd78518ed3e4a71a763
-- 
2.25.1