Re: [PATCH] ACPI: device-id: document struct acpi_device_id

[Andy Shevchenko <andriy.shevchenko@linux.intel.com>]

On Sun, Sep 13, 2026 at 11:51:05AM +0200, Miguel Garcia wrote:
> struct acpi_device_id lacks kernel-doc, so extracting documentation from
> its header describes ACPI_DEVICE_CLASS but not the matching table entry.

ACPI_DEVICE_CLASS()

> Document the four members, ID and class-code matching, and the table
> terminator. This complements the pending documentation header-split
> update without changing its include directives.

> An LLM drafted this comment and changelog after being asked to address
> the missing documentation noted in the header-split discussion. The
> field descriptions were checked against the ACPI matching code. The
> extracted documentation passes kernel-doc and a focused Sphinx HTML
> build with warnings treated as errors; checkpatch reports no warnings.

This paragraph is more for the comment, no need to include as is into
the commit message.

...

> +/**
> + * struct acpi_device_id - ACPI device matching table entry
> + * @id: NUL-terminated hardware ID (_HID) or compatible ID (_CID) to match.
> + * @driver_data: Data private to the driver.

> + * @cls: PCI-defined class, subclass and programming interface code (_CLS).
> + * @cls_msk: Mask selecting the class-code fields to match.

Hmm... The only driver which uses this is AHCI. Yeah, that's fine, of course,
but might be that in the future we can replace that with a traditional list of
_HID:s, who knows...

> + * Use @id for ID matching or ACPI_DEVICE_CLASS() for class-code matching.
> + * Terminate the table with an entry whose @id is empty and @cls is zero.
> + */

-- 
With Best Regards,
Andy Shevchenko