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

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

[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.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Fixes: 607ca0f742b7 ("Merge tag 'tty-6.0-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/tty")
Cc: stable@vger.kernel.org # 6.0
Cc: Jiri Slaby <jslaby@suse.cz>
Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.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

Re: [PATCH] docs/driver-api/miscellaneous: Remove kernel-doc of serial_core.c

[Jiri Slaby]

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 <jirislaby@kernel.org>

Thanks.

> Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
> Fixes: 607ca0f742b7 ("Merge tag 'tty-6.0-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/tty")
> Cc: stable@vger.kernel.org # 6.0
> Cc: Jiri Slaby <jslaby@suse.cz>
> Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
-- 
js
suse labs

Re: [PATCH] docs/driver-api/miscellaneous: Remove kernel-doc of serial_core.c

[Akira Yokosawa]

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 <akiyks@gmail.com>
> Fixes: 607ca0f742b7 ("Merge tag 'tty-6.0-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/tty")
> Cc: stable@vger.kernel.org # 6.0
> Cc: Jiri Slaby <jslaby@suse.cz>
> Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.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.

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

Re: [PATCH] docs/driver-api/miscellaneous: Remove kernel-doc of serial_core.c

[Akira Yokosawa]

Hi Jon,

On Wed, 9 Nov 2022 23:45:06 +0900, Akira Yokosawa wrote:
> 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 <akiyks@gmail.com>
>> Fixes: 607ca0f742b7 ("Merge tag 'tty-6.0-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/tty")
>> Cc: stable@vger.kernel.org # 6.0
>> Cc: Jiri Slaby <jslaby@suse.cz>
>> Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
>> ---
[...]
> 
> 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-docs-next.log	2022-11-21 22:18:19.787652881 +0900
+++ htmldocs-duplicate-backmerge-6.1-rc6.log	2022-11-21 22:18:33.563052797 +0900
@@ -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

Re: [PATCH] docs/driver-api/miscellaneous: Remove kernel-doc of serial_core.c

[Jonathan Corbet]

Akira Yokosawa <akiyks@gmail.com> writes:

> Hi Jon,
>
> On Wed, 9 Nov 2022 23:45:06 +0900, Akira Yokosawa wrote:
>> 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 <akiyks@gmail.com>
>>> Fixes: 607ca0f742b7 ("Merge tag 'tty-6.0-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/tty")
>>> Cc: stable@vger.kernel.org # 6.0
>>> Cc: Jiri Slaby <jslaby@suse.cz>
>>> Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
>>> ---
> [...]
>> 
>> 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-docs-next.log	2022-11-21 22:18:19.787652881 +0900
> +++ htmldocs-duplicate-backmerge-6.1-rc6.log	2022-11-21 22:18:33.563052797 +0900
> @@ -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

Re: [PATCH] docs/driver-api/miscellaneous: Remove kernel-doc of serial_core.c

[Jonathan Corbet]

Akira Yokosawa <akiyks@gmail.com> writes:

> Hi Jon,
>
> On Wed, 9 Nov 2022 23:45:06 +0900, Akira Yokosawa wrote:
>> 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 <akiyks@gmail.com>
>>> Fixes: 607ca0f742b7 ("Merge tag 'tty-6.0-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/tty")
>>> Cc: stable@vger.kernel.org # 6.0
>>> Cc: Jiri Slaby <jslaby@suse.cz>
>>> Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
>>> ---
> [...]
>> 
>> 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.

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

Re: [PATCH] docs/driver-api/miscellaneous: Remove kernel-doc of serial_core.c

[Akira Yokosawa]

On Mon, 21 Nov 2022 14:01:16 -0700, Jonathan Corbet wrote:
> 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

> 
> Thanks,
> 
> jon

Re: [PATCH] docs/driver-api/miscellaneous: Remove kernel-doc of serial_core.c

[Jonathan Corbet]

Akira Yokosawa <akiyks@gmail.com> writes:

> On Mon, 21 Nov 2022 14:01:16 -0700, Jonathan Corbet wrote:
>> 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