Re: [PATCH v3] Documentation: Update after split of <linux/mod_devicetable.h>

[Jonathan Corbet <corbet@lwn.net>]

Karl Mehltretter <kmehltretter@gmail.com> writes:

> From: Uwe Kleine-König (The Capable Hub) <u.kleine-koenig@baylibre.com>
>
> Most structs that were defined in <linux/mod_devicetable.h> before were
> moved to a bus specific header. Follow the movement to get the struct's
> documentation back.
>
> For the list of device ids in basics.rst use an explicit list of all the
> headers that have kernel-doc annotations and that are not described
> elsewhere (i.e. pci and mei_cl). <linux/device-id/acpi.h> is left out on
> purpose, ACPI_DEVICE_CLASS() is not a device id struct.
>
> Also repair the referencing in the zh_CN translation of pci.rst and
> don't duplicate `struct mei_cl_device_id`.
>
> Fixes: ad428f5811bd ("mod_devicetable.h: Split into per subsystem headers")
> Signed-off-by: Uwe Kleine-König (The Capable Hub) <u.kleine-koenig@baylibre.com>
> Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
> Tested-by: Randy Dunlap <rdunlap@infradead.org>
> [Karl Mehltretter: use the :file: role in pcmcia/driver.rst, say why
>  acpi.h is left out]
> Assisted-by: LLM
> Signed-off-by: Karl Mehltretter <kmehltretter@gmail.com>
> ---
> Changes since v2
>   https://lore.kernel.org/r/ede7ce64f20e10660ebf6bc1b41836dad750ae3b.1783349758.git.ukleinek@kernel.org/
> - use the :file: role for the header path in pcmcia/driver.rst (Randy)
> - say in the commit message that <linux/device-id/acpi.h> is left out on
>   purpose (question raised by the Sashiko review)
> - carried Randy's Reviewed-by and Tested-by from v2, the diff changed in
>   one line of markup only
> - Uwe asked me to take over the patch:
>   https://lore.kernel.org/r/apv6yQ1U-HhNglyV@monoceros/
>   It supersedes my PCI-only patch
>   https://lore.kernel.org/r/20260905084916.40196-1-kmehltretter@gmail.com/
>
> Randy's suggestion to add kernel-doc comments to <linux/mei_cl_bus.h> for
> struct mei_cl_driver and include those instead of the duplicated struct is
> left for a separate patch, it touches a header outside Documentation/.
>
>  Documentation/PCI/pci.rst                     |  2 +-
>  Documentation/driver-api/basics.rst           | 31 +++++++++++++++++--
>  .../driver-api/mei/mei-client-bus.rst         | 12 ++-----
>  Documentation/pcmcia/driver.rst               |  2 +-
>  Documentation/staging/rpmsg.rst               |  2 +-
>  Documentation/translations/zh_CN/PCI/pci.rst  |  8 ++---
>  6 files changed, 39 insertions(+), 18 deletions(-)

This one adds some new build warnings:

  Documentation/translations/zh_CN/PCI/pci:98: ./include/linux/pci.h:3: WARNING: Duplicate C declaration, also defined at PCI/pci:3.
  Declaration is '.. c:struct:: pci_driver'. [duplicate_declaration.c]
  kernel/Documentation/translations/zh_CN/PCI/pci:106: ./include/linux/device-id/pci.h:3: WARNING: Duplicate C declaration, also defined at PCI/pci:3.
  Declaration is '.. c:struct:: pci_device_id'. [duplicate_declaration.c]

jon