Add better documentation to fingerprint.h

Some vendors are confused by the use of errors vs acquired messages
This adds documentation on how they should be used.

Fixes bug 22728578

Change-Id: I5e6a8f7b159ec331a59202fa64b7320e43661429

1 files changed, 28 insertions, 10 deletions

diff --git a/include/hardware/fingerprint.h b/include/hardware/fingerprint.h
index 075e18b..ac88c10 100644
--- a/include/hardware/fingerprint.h
+++ b/include/hardware/fingerprint.h
@@ -31,23 +31,41 @@ typedef enum fingerprint_msg_type {
     FINGERPRINT_AUTHENTICATED = 5
 } fingerprint_msg_type_t;
 
+/*
+ * Fingerprint errors are meant to tell the framework to terminate the current operation and ask
+ * for the user to correct the situation. These will almost always result in messaging and user
+ * interaction to correct the problem.
+ *
+ * For example, FINGERPRINT_ERROR_CANCELED should follow any acquisition message that results in
+ * a situation where the current operation can't continue without user interaction. For example,
+ * if the sensor is dirty during enrollment and no further enrollment progress can be made,
+ * send FINGERPRINT_ACQUIRED_IMAGER_DIRTY followed by FINGERPRINT_ERROR_CANCELED.
+ */
 typedef enum fingerprint_error {
-    FINGERPRINT_ERROR_HW_UNAVAILABLE = 1,
-    FINGERPRINT_ERROR_UNABLE_TO_PROCESS = 2,
-    FINGERPRINT_ERROR_TIMEOUT = 3,
+    FINGERPRINT_ERROR_HW_UNAVAILABLE = 1, /* The hardware has an error that can't be resolved. */
+    FINGERPRINT_ERROR_UNABLE_TO_PROCESS = 2, /* Bad data; operation can't continue */
+    FINGERPRINT_ERROR_TIMEOUT = 3, /* The operation has timed out waiting for user input. */
     FINGERPRINT_ERROR_NO_SPACE = 4, /* No space available to store a template */
-    FINGERPRINT_ERROR_CANCELED = 5,
-    FINGERPRINT_ERROR_UNABLE_TO_REMOVE = 6, /* fingerprint id can't be removed */
+    FINGERPRINT_ERROR_CANCELED = 5, /* The current operation can't proceed. See above. */
+    FINGERPRINT_ERROR_UNABLE_TO_REMOVE = 6, /* fingerprint with given id can't be removed */
     FINGERPRINT_ERROR_VENDOR_BASE = 1000 /* vendor-specific error messages start here */
 } fingerprint_error_t;
 
+/*
+ * Fingerprint acquisition info is meant as feedback for the current operation.  Anything but
+ * FINGERPRINT_ACQUIRED_GOOD will be shown to the user as feedback on how to take action on the
+ * current operation. For example, FINGERPRINT_ACQUIRED_IMAGER_DIRTY can be used to tell the user
+ * to clean the sensor.  If this will cause the current operation to fail, an additional
+ * FINGERPRINT_ERROR_CANCELED can be sent to stop the operation in progress (e.g. enrollment).
+ * In general, these messages will result in a "Try again" message.
+ */
 typedef enum fingerprint_acquired_info {
     FINGERPRINT_ACQUIRED_GOOD = 0,
-    FINGERPRINT_ACQUIRED_PARTIAL = 1,
-    FINGERPRINT_ACQUIRED_INSUFFICIENT = 2,
-    FINGERPRINT_ACQUIRED_IMAGER_DIRTY = 3,
-    FINGERPRINT_ACQUIRED_TOO_SLOW = 4,
-    FINGERPRINT_ACQUIRED_TOO_FAST = 5,
+    FINGERPRINT_ACQUIRED_PARTIAL = 1, /* sensor needs more data, i.e. longer swipe. */
+    FINGERPRINT_ACQUIRED_INSUFFICIENT = 2, /* image doesn't contain enough detail for recognition*/
+    FINGERPRINT_ACQUIRED_IMAGER_DIRTY = 3, /* sensor needs to be cleaned */
+    FINGERPRINT_ACQUIRED_TOO_SLOW = 4, /* mostly swipe-type sensors; not enough data collected */
+    FINGERPRINT_ACQUIRED_TOO_FAST = 5, /* for swipe and area sensors; tell user to slow down*/
     FINGERPRINT_ACQUIRED_VENDOR_BASE = 1000 /* vendor-specific acquisition messages start here */
 } fingerprint_acquired_info_t;