docs/driver-api/miscellaneous: Remove kernel-doc of serial_core.c
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.
---
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
@@ -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
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.cinserial/drivers.rstadded in the merge. It conflicts with an existing kernel-doc directive inmiscellaneous.rst.Remove the latter directive and resolve the duplicates.
Thanks.
Quoted 5 lines
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.0Cc Jiri Slaby <[email protected]>Cc Greg Kroah-Hartman <[email protected]>
Signature · 2 lines
js suse labs
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.cinserial/drivers.rstadded in the merge. It conflicts with an existing kernel-doc directive inmiscellaneous.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.0Cc 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:: structuart_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:: voiduart_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:: structuart_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.rstadded 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@@ -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
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.cinserial/drivers.rstadded in the merge. It conflicts with an existing kernel-doc directive inmiscellaneous.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.0Cc 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
Jonathan Corbet
maintainerQuoted 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.cinserial/drivers.rstadded in the merge. It conflicts with an existing kernel-doc directive inmiscellaneous.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.0Cc 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 ofserial_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, commitc18c20f16219("mm, slab: remove duplicate kernel-doc comment forksize()") 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
Jonathan Corbet
maintainerQuoted 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.cinserial/drivers.rstadded in the merge. It conflicts with an existing kernel-doc directive inmiscellaneous.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.0Cc 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 ofserial_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, commitc18c20f16219("mm, slab: remove duplicate kernel-doc comment forksize()") 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
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
Jonathan Corbet
maintainerQuoted 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