From ca148cbcf1926a4b0627a599fa80ed812aa97c40 Mon Sep 17 00:00:00 2001
From: Bastien Nocera <hadess@hadess.net>
Date: Mon, 12 Nov 2018 15:59:43 +0100
Subject: [PATCH] lib: Add documentation for usb_id

---
 libfprint/fp_internal.h | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/libfprint/fp_internal.h b/libfprint/fp_internal.h
index 95b212b..6301982 100644
--- a/libfprint/fp_internal.h
+++ b/libfprint/fp_internal.h
@@ -131,6 +131,33 @@ struct fp_img_dev {
 };
 
 /* fp_driver structure definition */
+
+/**
+ * usb_id:
+ * @vendor: the USB vendor ID
+ * @product: the USB product ID
+ * @driver_data: data to differentiate devices of different
+ *   vendor and product IDs.
+ *
+ * The struct #usb_id is used to declare devices supported by a
+ * particular driver. The @driver_data information is used to
+ * differentiate different models of devices which only need
+ * small changes compared to the default driver behaviour to function.
+ *
+ * For example, a device might have a different initialisation from
+ * the stock device, so the driver could do:
+ *
+ * |[<!-- language="C" -->
+ *    if (driver_data == MY_DIFFERENT_DEVICE_QUIRK) {
+ *        ...
+ *    } else {
+ *        ...
+ *    }
+ * ]|
+ *
+ * The default value is zero, so the @driver_data needs to be a
+ * non-zero to be useful.
+ */
 struct usb_id {
 	uint16_t vendor;
 	uint16_t product;