Skip to contentSkip to conversation

docs/driver-api/miscellaneous: Remove kernel-doc of serial_core.c

PATCH In review Akira Yokosawa 3 participants 8 messages Nov 2, 2022 – Nov 21, 2022 Documentation

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 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.

Fixes 607ca0f742b7 ("Merge tag 'tty-6.0-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/tty")
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(-)
Documentation/driver-api/miscellaneous.rst +2 -3
index 304ffb146cf9..4a5104a368ac 100644
@@ -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

Signature · 1 line
2.25.1
Reviewed-by on v1 1/1
#1 lore raw
Quoted 9 lines · Akira Yokosawa

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.

Thanks.

Quoted 5 lines
Fixes 607ca0f742b7 ("Merge tag 'tty-6.0-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/tty")
Cc Jiri Slaby <[email protected]>
Cc Greg Kroah-Hartman <[email protected]>
Signature · 2 lines
js
suse labs
#2 lore raw
In reply to Akira Yokosawa

Hi Jon,

Quoted 47 lines · Akira Yokosawa

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.

Fixes 607ca0f742b7 ("Merge tag 'tty-6.0-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/tty")
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.

Quoted 6 lines

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

Quoted 29 lines

Thanks,
Akira

--

 Documentation/driver-api/miscellaneous.rst | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)
Documentation/driver-api/miscellaneous.rst +2 -3
index 304ffb146cf9..4a5104a368ac 100644
@@ -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

#3 lore raw

Hi Jon,

Quoted 19 lines · Akira Yokosawa

Hi Jon,

Quoted 16 lines · Akira Yokosawa

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.

Fixes 607ca0f742b7 ("Merge tag 'tty-6.0-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/tty")
Cc Jiri Slaby <[email protected]>
Cc Greg Kroah-Hartman <[email protected]>

---

[...]

Quoted 4 lines

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.

This change has landed at v6.1-rc6 as commit 3ec17cb325ac ("docs/driver-api/miscellaneous: Remove kernel-doc of serial_core.c"). Can you please consider backmerging v6.1-rc6?
There is another fix landed at v6.1-rc5 which fixed another duplicate kernel-doc, commit c18c20f16219 ("mm, slab: remove duplicate kernel-doc comment for ksize()") authored by Vlastimil.

For your reference, appended below is the diff of warnings of duplicate from Sphinx >=3.1 (line numbers are omitted):

htmldocs-duplicate-backmerge-6.1-rc6.log renamed from htmldocs-duplicate-docs-next.log +0 -122
@@ -4,126 +4,6 @@
 Declaration is '.. c:function:: int ssam_request_sync (struct ssam_controller *ctrl, const struct ssam_request *spec, struct ssam_response *rsp)'.
 /linux/Documentation/driver-api/usb/usb: ./drivers/usb/core/message.c: WARNING: Duplicate C declaration, also defined at driver-api/usb/gadget.
 Declaration is '.. c:function:: int usb_string (struct usb_device *dev, int index, char *buf, size_t size)'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:function:: void uart_write_wakeup(struct uart_port *port)'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: struct uart_port *port'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-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: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: struct uart_port *port'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: unsigned int cflag'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: unsigned int baud'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:function:: unsigned int uart_get_baud_rate(struct uart_port *port, struct ktermios *termios, const struct ktermios *old, unsigned int min, unsigned int max)'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: struct uart_port *port'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: struct ktermios *termios'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: const struct ktermios *old'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: unsigned int min'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: unsigned int max'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:function:: unsigned int uart_get_divisor(struct uart_port *port, unsigned int baud)'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: struct uart_port *port'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: unsigned int baud'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:function:: void uart_console_write(struct uart_port *port, const char *s, unsigned int count, void (*putchar)(struct uart_port*, unsigned char))'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: struct uart_port *port'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: const char *s'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: unsigned int count'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: void (*putchar)(struct uart_port*, unsigned char)'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:function:: int uart_parse_earlycon(char *p, unsigned char *iotype, resource_size_t *addr, char **options)'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: char *p'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: unsigned char *iotype'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: resource_size_t *addr'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: char **options'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:function:: void uart_parse_options(const char *options, int *baud, int *parity, int *bits, int *flow)'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: const char *options'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: int *baud'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: int *parity'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: int *bits'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: int *flow'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:function:: int uart_set_options(struct uart_port *port, struct console *co, int baud, int parity, int bits, int flow)'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: struct uart_port *port'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: struct console *co'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: int baud'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: int parity'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: int bits'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: int flow'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:function:: int uart_register_driver(struct uart_driver *drv)'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: struct uart_driver *drv'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:function:: void uart_unregister_driver(struct uart_driver *drv)'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: struct uart_driver *drv'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:function:: int uart_add_one_port(struct uart_driver *drv, struct uart_port *uport)'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: struct uart_driver *drv'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: struct uart_port *uport'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:function:: int uart_remove_one_port(struct uart_driver *drv, struct uart_port *uport)'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: struct uart_driver *drv'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: struct uart_port *uport'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:function:: bool uart_match_port(const struct uart_port *port1, const struct uart_port *port2)'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: const struct uart_port *port1'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: const struct uart_port *port2'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:function:: void uart_handle_dcd_change(struct uart_port *uport, unsigned int status)'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: struct uart_port *uport'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: unsigned int status'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:function:: void uart_handle_cts_change(struct uart_port *uport, unsigned int status)'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: struct uart_port *uport'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: unsigned int status'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:function:: bool uart_try_toggle_sysrq(struct uart_port *port, unsigned int ch)'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: struct uart_port *port'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: unsigned int ch'.
 /linux/Documentation/driver-api/usb/usb.rst: WARNING: Duplicate C declaration, also defined at driver-api/usb/gadget.
 Declaration is '.. c:struct:: usb_string'.
 /linux/Documentation/gpu/amdgpu/driver-core: ./drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c: WARNING: Duplicate C declaration, also defined at gpu/amdgpu/driver-core.
@@ -142,5 +22,3 @@
 Declaration is '.. c:function:: void cfg80211_rx_assoc_resp (struct net_device *dev, struct cfg80211_rx_assoc_resp *data)'.
 /linux/Documentation/driver-api/80211/mac80211: ./include/net/mac80211.h: WARNING: Duplicate C declaration, also defined at driver-api/80211/mac80211.
 Declaration is '.. c:function:: void ieee80211_tx_status (struct ieee80211_hw *hw, struct sk_buff *skb)'.
-/linux/Documentation/core-api/mm-api: ./mm/slab_common.c: WARNING: Duplicate C declaration, also defined at core-api/mm-api.
-Declaration is '.. c:function:: size_t ksize (const void *objp)'.

Thanks, Akira

maintainer
#4 lore raw
Quoted 175 lines · Akira Yokosawa

Hi Jon,

Quoted 19 lines · Akira Yokosawa

Hi Jon,

Quoted 16 lines · Akira Yokosawa

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.

Fixes 607ca0f742b7 ("Merge tag 'tty-6.0-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/tty")
Cc Jiri Slaby <[email protected]>
Cc Greg Kroah-Hartman <[email protected]>

---

[...]

Quoted 4 lines

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.

This change has landed at v6.1-rc6 as commit 3ec17cb325ac ("docs/driver-api/miscellaneous: Remove kernel-doc of serial_core.c"). Can you please consider backmerging v6.1-rc6?
There is another fix landed at v6.1-rc5 which fixed another duplicate kernel-doc, commit c18c20f16219 ("mm, slab: remove duplicate kernel-doc comment for ksize()") authored by Vlastimil.

For your reference, appended below is the diff of warnings of duplicate from Sphinx >=3.1 (line numbers are omitted):

htmldocs-duplicate-backmerge-6.1-rc6.log renamed from htmldocs-duplicate-docs-next.log +0 -122
@@ -4,126 +4,6 @@
 Declaration is '.. c:function:: int ssam_request_sync (struct ssam_controller *ctrl, const struct ssam_request *spec, struct ssam_response *rsp)'.
 /linux/Documentation/driver-api/usb/usb: ./drivers/usb/core/message.c: WARNING: Duplicate C declaration, also defined at driver-api/usb/gadget.
 Declaration is '.. c:function:: int usb_string (struct usb_device *dev, int index, char *buf, size_t size)'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:function:: void uart_write_wakeup(struct uart_port *port)'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: struct uart_port *port'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-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: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: struct uart_port *port'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: unsigned int cflag'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: unsigned int baud'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:function:: unsigned int uart_get_baud_rate(struct uart_port *port, struct ktermios *termios, const struct ktermios *old, unsigned int min, unsigned int max)'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: struct uart_port *port'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: struct ktermios *termios'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: const struct ktermios *old'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: unsigned int min'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: unsigned int max'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:function:: unsigned int uart_get_divisor(struct uart_port *port, unsigned int baud)'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: struct uart_port *port'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: unsigned int baud'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:function:: void uart_console_write(struct uart_port *port, const char *s, unsigned int count, void (*putchar)(struct uart_port*, unsigned char))'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: struct uart_port *port'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: const char *s'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: unsigned int count'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: void (*putchar)(struct uart_port*, unsigned char)'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:function:: int uart_parse_earlycon(char *p, unsigned char *iotype, resource_size_t *addr, char **options)'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: char *p'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: unsigned char *iotype'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: resource_size_t *addr'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: char **options'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:function:: void uart_parse_options(const char *options, int *baud, int *parity, int *bits, int *flow)'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: const char *options'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: int *baud'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: int *parity'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: int *bits'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: int *flow'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:function:: int uart_set_options(struct uart_port *port, struct console *co, int baud, int parity, int bits, int flow)'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: struct uart_port *port'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: struct console *co'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: int baud'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: int parity'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: int bits'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: int flow'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:function:: int uart_register_driver(struct uart_driver *drv)'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: struct uart_driver *drv'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:function:: void uart_unregister_driver(struct uart_driver *drv)'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: struct uart_driver *drv'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:function:: int uart_add_one_port(struct uart_driver *drv, struct uart_port *uport)'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: struct uart_driver *drv'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: struct uart_port *uport'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:function:: int uart_remove_one_port(struct uart_driver *drv, struct uart_port *uport)'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: struct uart_driver *drv'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: struct uart_port *uport'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:function:: bool uart_match_port(const struct uart_port *port1, const struct uart_port *port2)'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: const struct uart_port *port1'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: const struct uart_port *port2'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:function:: void uart_handle_dcd_change(struct uart_port *uport, unsigned int status)'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: struct uart_port *uport'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: unsigned int status'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:function:: void uart_handle_cts_change(struct uart_port *uport, unsigned int status)'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: struct uart_port *uport'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: unsigned int status'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:function:: bool uart_try_toggle_sysrq(struct uart_port *port, unsigned int ch)'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: struct uart_port *port'.
-/linux/Documentation/driver-api/serial/driver.rst: WARNING: Duplicate C declaration, also defined at driver-api/miscellaneous.
-Declaration is '.. c:None:: unsigned int ch'.
 /linux/Documentation/driver-api/usb/usb.rst: WARNING: Duplicate C declaration, also defined at driver-api/usb/gadget.
 Declaration is '.. c:struct:: usb_string'.
 /linux/Documentation/gpu/amdgpu/driver-core: ./drivers/gpu/drm/amd/amdgpu/amdgpu_vm.c: WARNING: Duplicate C declaration, also defined at gpu/amdgpu/driver-core.
@@ -142,5 +22,3 @@
 Declaration is '.. c:function:: void cfg80211_rx_assoc_resp (struct net_device *dev, struct cfg80211_rx_assoc_resp *data)'.
 /linux/Documentation/driver-api/80211/mac80211: ./include/net/mac80211.h: WARNING: Duplicate C declaration, also defined at driver-api/80211/mac80211.
 Declaration is '.. c:function:: void ieee80211_tx_status (struct ieee80211_hw *hw, struct sk_buff *skb)'.
-/linux/Documentation/core-api/mm-api: ./mm/slab_common.c: WARNING: Duplicate C declaration, also defined at core-api/mm-api.
-Declaration is '.. c:function:: size_t ksize (const void *objp)'.

Thanks, Akira

maintainer
#5 lore raw
In reply to Akira Yokosawa
Quoted 28 lines · Akira Yokosawa

Hi Jon,

Quoted 19 lines · Akira Yokosawa

Hi Jon,

Quoted 16 lines · Akira Yokosawa

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.

Fixes 607ca0f742b7 ("Merge tag 'tty-6.0-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/tty")
Cc Jiri Slaby <[email protected]>
Cc Greg Kroah-Hartman <[email protected]>

---

[...]

Quoted 4 lines

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.

Quoted 6 lines

This change has landed at v6.1-rc6 as commit 3ec17cb325ac ("docs/driver-api/miscellaneous: Remove kernel-doc of serial_core.c"). Can you please consider backmerging v6.1-rc6?
There is another fix landed at v6.1-rc5 which fixed another duplicate kernel-doc, commit c18c20f16219 ("mm, slab: remove duplicate kernel-doc comment for ksize()") authored by Vlastimil.

So the purpose of this backmerge would be just to get rid of a few warnings in docs-next for the next few weeks? Given the jaundiced eye with which Linus looks at backmerges, I'm inclined to just wait and let it all settle out during the merge window. Is there any work that would be impeded by not doing that merge now?

Thanks,

jon

#6 lore raw
Quoted 5 lines · Jonathan Corbet

So the purpose of this backmerge would be just to get rid of a few warnings in docs-next for the next few weeks? Given the jaundiced eye with which Linus looks at backmerges, I'm inclined to just wait and let it all settle out during the merge window. Is there any work that would be impeded by not doing that merge now?

I thought the backmerge might reduce your annoyance when test-building for the next merge window with Sphinx >=3.1.
You call those dozes of warnings *a few*.
Of course, I can wait. :-)

Thanks, Akira

Quoted 4 lines

Thanks,

jon

maintainer
#7 lore raw
Quoted 10 lines · Akira Yokosawa
Quoted 5 lines · Jonathan Corbet

So the purpose of this backmerge would be just to get rid of a few warnings in docs-next for the next few weeks? Given the jaundiced eye with which Linus looks at backmerges, I'm inclined to just wait and let it all settle out during the merge window. Is there any work that would be impeded by not doing that merge now?

I thought the backmerge might reduce your annoyance when test-building for the next merge window with Sphinx >=3.1.
You call those dozes of warnings *a few*.
Of course, I can wait. :-)

Hey, I raised two kids, I'm good at dealing with annoyance...:)

Thanks,

jon