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

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

[Miguel Garcia]

struct acpi_device_id lacks kernel-doc, so extracting documentation from
its header describes ACPI_DEVICE_CLASS but not the matching table entry.

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.

Link: https://lore.kernel.org/all/aqEWUBf1pewPP_K2@monoceros/
Assisted-by: LLM
Signed-off-by: Miguel Garcia <miguelgarciaroman8@gmail.com>
---
 include/linux/device-id/acpi.h | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/include/linux/device-id/acpi.h b/include/linux/device-id/acpi.h
index 65800cefd..8c3b30ebf 100644
--- a/include/linux/device-id/acpi.h
+++ b/include/linux/device-id/acpi.h
@@ -9,6 +9,16 @@ typedef unsigned long kernel_ulong_t;
 
 #define ACPI_ID_LEN	16
 
+/**
+ * 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.
+ *
+ * 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.
+ */
 struct acpi_device_id {
 	__u8 id[ACPI_ID_LEN];
 	kernel_ulong_t driver_data;
-- 
2.43.0

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

[Andy Shevchenko]

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