API documentation

libfprint/fprint.h

@@ -31,17 +31,23 @@ struct fp_print_data;
 struct fp_img;
 
 /* misc/general stuff */
+
+/** \ingroup print_data
+ * Numeric codes used to refer to fingers (and thumbs) of a human. These are
+ * purposely not available as strings, to avoid getting the library tangled up
+ * in localization efforts.
+ */
 enum fp_finger {
-	LEFT_THUMB = 1,
-	LEFT_INDEX,
-	LEFT_MIDDLE,
-	LEFT_RING,
-	LEFT_LITTLE,
-	RIGHT_THUMB,
-	RIGHT_INDEX,
-	RIGHT_MIDDLE,
-	RIGHT_RING,
-	RIGHT_LITTLE,
+	LEFT_THUMB = 1, /** thumb (left hand) */
+	LEFT_INDEX, /** index finger (left hand) */
+	LEFT_MIDDLE, /** middle finger (left hand) */
+	LEFT_RING, /** ring finger (left hand) */
+	LEFT_LITTLE, /** little finger (left hand) */
+	RIGHT_THUMB, /** thumb (right hand) */
+	RIGHT_INDEX, /** index finger (right hand) */
+	RIGHT_MIDDLE, /** middle finger (right hand) */
+	RIGHT_RING, /** ring finger (right hand) */
+	RIGHT_LITTLE, /** little finger (right hand) */
 };
 
 /* Drivers */
@@ -90,26 +96,65 @@ int fp_dev_img_capture(struct fp_dev *dev, int unconditional,
 int fp_dev_get_img_width(struct fp_dev *dev);
 int fp_dev_get_img_height(struct fp_dev *dev);
 
-/* Enrollment */
+/** \ingroup dev
+ * Enrollment result codes returned from fp_enroll_finger().
+ * Result codes with RETRY in the name suggest that the scan failed due to
+ * user error. Applications will generally want to inform the user of the
+ * problem and then retry the enrollment stage. For more info on the semantics
+ * of interpreting these result codes and tracking enrollment process, see
+ * \ref enrolling.
+ */
 enum fp_enroll_result {
+	/** Enrollment completed successfully, the enrollment data has been
+	 * returned to the caller. */
 	FP_ENROLL_COMPLETE = 1,
+	/** Enrollment failed due to incomprehensible data; this may occur when
+	 * the user scans a different finger on each enroll stage. */
 	FP_ENROLL_FAIL,
+	/** Enroll stage passed; more stages are need to complete the process. */
 	FP_ENROLL_PASS,
+	/** The enrollment scan did not succeed due to poor scan quality or
+	 * other general user scanning problem. */
 	FP_ENROLL_RETRY = 100,
+	/** The enrollment scan did not succeed because the finger swipe was
+	 * too short. */
 	FP_ENROLL_RETRY_TOO_SHORT,
+	/** The enrollment scan did not succeed because the finger was not
+	 * centered on the scanner. */
 	FP_ENROLL_RETRY_CENTER_FINGER,
+	/** The verification scan did not succeed due to quality or pressure
+	 * problems; the user should remove their finger from the scanner before
+	 * retrying. */
 	FP_ENROLL_RETRY_REMOVE_FINGER,
 };
 
 int fp_enroll_finger(struct fp_dev *dev, struct fp_print_data **print_data);
 
-/* Verification */
+/** \ingroup dev
+ * Verification result codes returned from fp_verify_finger().
+ * Result codes with RETRY in the name suggest that the scan failed due to
+ * user error. Applications will generally want to inform the user of the
+ * problem and then retry the verify operation.
+ */
 enum fp_verify_result {
+	/** The verification scan completed successfully, but the newly scanned
+	 * fingerprint does not match the fingerprint being verified against. */
 	FP_VERIFY_NO_MATCH = 0,
+	/** The verification scan completed successfully and the newly scanned
+	 * fingerprint does match the fingerprint being verified. */
 	FP_VERIFY_MATCH = 1,
+	/** The verification scan did not succeed due to poor scan quality or
+	 * other general user scanning problem. */
 	FP_VERIFY_RETRY = FP_ENROLL_RETRY,
+	/** The verification scan did not succeed because the finger swipe was
+	 * too short. */
 	FP_VERIFY_RETRY_TOO_SHORT = FP_ENROLL_RETRY_TOO_SHORT,
+	/** The verification scan did not succeed because the finger was not
+	 * centered on the scanner. */
 	FP_VERIFY_RETRY_CENTER_FINGER = FP_ENROLL_RETRY_CENTER_FINGER,
+	/** The verification scan did not succeed due to quality or pressure
+	 * problems; the user should remove their finger from the scanner before
+	 * retrying. */
 	FP_VERIFY_RETRY_REMOVE_FINGER = FP_ENROLL_RETRY_REMOVE_FINGER,
 };