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

[Miguel García Román]

Thanks Andy, agreed on both points. For v2, I'll use
ACPI_DEVICE_CLASS() in the commit message and move the drafting and
validation notes below the --- separator.

Miguel


On Mon, 14 Sep 2026 16:11:43 +0300, Andy Shevchenko
<andriy.shevchenko@xxxxxxxxxxxxxxx> wrote:
> 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