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

linux-doc.vger.kernel.org archive mirror
 help / color / mirror / Atom feed

From: Jonathan Corbet <corbet@lwn.net>
To: Akira Yokosawa <akiyks@gmail.com>
Cc: linux-doc@vger.kernel.org, Akira Yokosawa <akiyks@gmail.com>
Subject: Re: [PATCH] docs/driver-api/miscellaneous: Remove kernel-doc of serial_core.c
Date: Mon, 21 Nov 2022 13:59:21 -0700	[thread overview]
Message-ID: <87sfic9g7q.fsf@meer.lwn.net> (raw)
In-Reply-To: <9f23e62c-1401-cf58-f99b-fa804366cd4c@gmail.com>

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

next prev parent reply	other threads:[~2022-11-21 20:59 UTC|newest]

Thread overview: 8+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2022-11-02 11:48 [PATCH] docs/driver-api/miscellaneous: Remove kernel-doc of serial_core.c Akira Yokosawa
2022-11-03  6:35 ` Jiri Slaby
2022-11-09 14:45 ` Akira Yokosawa
2022-11-21 13:46   ` Akira Yokosawa
2022-11-21 20:59     ` Jonathan Corbet [this message]
2022-11-21 21:01     ` Jonathan Corbet
2022-11-21 23:10       ` Akira Yokosawa
2022-11-21 23:29         ` Jonathan Corbet

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=87sfic9g7q.fsf@meer.lwn.net \
    --to=corbet@lwn.net \
    --cc=akiyks@gmail.com \
    --cc=linux-doc@vger.kernel.org \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

Be sure your reply has a Subject: header at the top and a blank line before the message body.

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).