From 4012a4fe6fe43da3f85fb564f0d01a08e5cfa3e0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Marco=20Trevisan=20=28Trevi=C3=B1o=29?= <mail@3v1n0.net>
Date: Fri, 15 Jul 2022 22:51:11 +0200
Subject: [PATCH] fpi-device: Clarify identify prints gallery usage in drivers
 docs

---
 libfprint/fpi-device.c | 33 +++++++++++++++++++++++++++------
 1 file changed, 27 insertions(+), 6 deletions(-)

diff --git a/libfprint/fpi-device.c b/libfprint/fpi-device.c
index 36f8ccad..b5ccb4c7 100644
--- a/libfprint/fpi-device.c
+++ b/libfprint/fpi-device.c
@@ -622,7 +622,14 @@ fpi_device_get_verify_data (FpDevice *device,
  * @device: The #FpDevice
  * @prints: (out) (transfer none) (element-type FpPrint): The gallery of prints
  *
- * Get data for identify.
+ * Get prints gallery for identification.
+ *
+ * The @prints array is always non-%NULL and may contain a list of #FpPrint's
+ * that the device should match against.
+ *
+ * Note that @prints can be an empty array, in such case the device is expected
+ * to report the scanned print matching the one in its internal storage, if any.
+ *
  */
 void
 fpi_device_get_identify_data (FpDevice   *device,
@@ -2009,12 +2016,26 @@ fpi_device_verify_report (FpDevice      *device,
  * fpi_device_identify_report:
  * @device: The #FpDevice
  * @match: (transfer none): The #FpPrint from the gallery that matched
- * @print: (transfer floating): The scanned #FpPrint
- * @error: A #GError if result is %FPI_MATCH_ERROR
+ * @print: (transfer floating): The scanned #FpPrint, set in the absence
+ *   of an error.
+ * @error: A #GError of %FP_DEVICE_RETRY type if @match and @print are unset.
  *
- * Report the result of a identify operation. Note that the passed @error must be
- * a retry error with the %FP_DEVICE_RETRY domain. For all other error cases,
- * the error should passed to fpi_device_identify_complete().
+ * Report the results of an identify operation.
+ *
+ * In case of successful identification @match is expected to be set to a
+ * #FpPrint that matches one from the provided gallery, while @print
+ * represents the scanned print and will be different.
+ *
+ * If there are no errors, it's expected that the device always reports the
+ * recognized @print even if there is no @match with the provided gallery (that
+ * can be potentially empty). This is required for application logic further
+ * up in the stack, such as for enroll-duplicate checking. @print needs to be
+ * sufficiently filled to do a comparison.
+ *
+ * In case of error, both @match and @print are expected to be %NULL.
+ * Note that the passed @error must be a retry error from the %FP_DEVICE_RETRY
+ * domain. For all other error cases, the error should passed to
+ * fpi_device_identify_complete().
  */
 void
 fpi_device_identify_report (FpDevice *device,