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

[Andy Shevchenko]

On Tue, Sep 08, 2026 at 09:00:31AM +0200, Karl Mehltretter wrote:
> From: Uwe Kleine-König (The Capable Hub) <u.kleine-koenig@xxxxxxxxxxxx>
> 
> 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.

Huh?! The device-id/acpi.h provides the ACPI device ID definition.

> 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@xxxxxxxxxxxx>

...

> Changes since v2
>   https://lore.kernel.org/r/ede7ce64f20e10660ebf6bc1b41836dad750ae3b.1783349758.git.ukleinek@xxxxxxxxxx/
> - 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)

I am unsatisfied with how the ACPI division was handled in the above mentioned
split. Id est the include/device-id/acpi.h is *the* header that has to be used
for the IDs, not the respective "include all" linux/acpi.h.
Hence the documentation has to allow the use of the device-id/*.h directly in
the drivers (most of the cases for ACPI).

Alternatively the OF ID *and* ACPI ID must be included to the upper lever bus
headers. So, spi.h, i2c.h, platform_device.h and so on has to *always* provide
both.

> - 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@xxxxxxxxx/
> 
> 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/.

Uwe, can you fix that?

-- 
With Best Regards,
Andy Shevchenko