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 <[email protected]>
Fixes: 607ca0f742b7 ("Merge tag 'tty-6.0-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/tty")
Cc: [email protected] # 6.0
Cc: Jiri Slaby <[email protected]>
Cc: Greg Kroah-Hartman <[email protected]>
---
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
On 02. 11. 22, 12:48, Akira Yokosawa wrote:
> 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.
Reviewed-by: Jiri Slaby <[email protected]>
Thanks.
> Signed-off-by: Akira Yokosawa <[email protected]>
> Fixes: 607ca0f742b7 ("Merge tag 'tty-6.0-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/tty")
> Cc: [email protected] # 6.0
> Cc: Jiri Slaby <[email protected]>
> Cc: Greg Kroah-Hartman <[email protected]>
--
js
suse labs
Hi Jon,
On Wed, 2 Nov 2022 20:48:01 +0900, Akira Yokosawa wrote:
> 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 <[email protected]>
> Fixes: 607ca0f742b7 ("Merge tag 'tty-6.0-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/tty")
> Cc: [email protected] # 6.0
> Cc: Jiri Slaby <[email protected]>
> Cc: Greg Kroah-Hartman <[email protected]>
> ---
> 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.
Jon, Greg has added this to his tty tree and (hopefully) it will
soon land Linus' tree (v6.1-rcX).
I'll ask you a back-merge once it happens.
Thanks, Akira
>
> 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