include: Update comments for fp_capture_type

BRANCH=none
BUG=b:226672013
TEST=./util/compare_build.sh -b all -j 120
     => MATCH

Signed-off-by: Tom Hughes <tomhughes@chromium.org>
Change-Id: I5d0fcf79c49087929875845d23dd73ae919ce8b0
Reviewed-on: https://chromium-review.googlesource.com/c/chromiumos/platform/ec/+/3602218
Reviewed-by: Andrea Grandi <agrandi@google.com>

2 files changed, 25 insertions, 12 deletions

diff --git a/include/ec_commands.h b/include/ec_commands.h
index 1aff487bbe..a226674907 100644
--- a/include/ec_commands.h
+++ b/include/ec_commands.h
@@ -7186,22 +7186,28 @@ struct ec_params_fp_passthru {
 /* Capture types defined in bits [30..28] */
 #define FP_MODE_CAPTURE_TYPE_SHIFT 28
 #define FP_MODE_CAPTURE_TYPE_MASK  (0x7 << FP_MODE_CAPTURE_TYPE_SHIFT)
-/*
- * This enum must remain ordered, if you add new values you must ensure that
- * FP_CAPTURE_TYPE_MAX is still the last one.
+/**
+ * enum fp_capture_type - Specifies the "mode" when capturing images.
+ *
+ * @FP_CAPTURE_VENDOR_FORMAT: Capture 1-3 images and choose the best quality
+ * image (produces 'frame_size' bytes)
+ * @FP_CAPTURE_SIMPLE_IMAGE: Simple raw image capture (produces width x height x
+ * bpp bits)
+ * @FP_CAPTURE_PATTERN0: Self test pattern (e.g. checkerboard)
+ * @FP_CAPTURE_PATTERN1: Self test pattern (e.g. inverted checkerboard)
+ * @FP_CAPTURE_QUALITY_TEST: Capture for Quality test with fixed contrast
+ * @FP_CAPTURE_RESET_TEST: Capture for pixel reset value test
+ * @FP_CAPTURE_TYPE_MAX: End of enum
+ *
+ * @note This enum must remain ordered, if you add new values you must ensure
+ * that FP_CAPTURE_TYPE_MAX is still the last one.
  */
 enum fp_capture_type {
-	/* Full blown vendor-defined capture (produces 'frame_size' bytes) */
 	FP_CAPTURE_VENDOR_FORMAT = 0,
-	/* Simple raw image capture (produces width x height x bpp bits) */
 	FP_CAPTURE_SIMPLE_IMAGE = 1,
-	/* Self test pattern (e.g. checkerboard) */
 	FP_CAPTURE_PATTERN0 = 2,
-	/* Self test pattern (e.g. inverted checkerboard) */
 	FP_CAPTURE_PATTERN1 = 3,
-	/* Capture for Quality test with fixed contrast */
 	FP_CAPTURE_QUALITY_TEST = 4,
-	/* Capture for pixel reset value test */
 	FP_CAPTURE_RESET_TEST = 5,
 	FP_CAPTURE_TYPE_MAX,
 };
diff --git a/include/fpsensor.h b/include/fpsensor.h
index 2c5baa2679..485d85e5c1 100644
--- a/include/fpsensor.h
+++ b/include/fpsensor.h
@@ -87,12 +87,19 @@ enum finger_state fp_sensor_finger_status(void);
 #define FP_SENSOR_LOW_SENSOR_COVERAGE 3
 int fp_sensor_acquire_image(uint8_t *image_data);
 
-/*
+/**
  * Acquires a fingerprint image with specific capture mode.
  *
- * Same as the fp_sensor_acquire_image function above,
- * excepted 'mode' can be set to one of the FP_CAPTURE_ constants
+ * Same as the fp_sensor_acquire_image function(),
+ * except @p mode can be set to one of the fp_capture_type constants
  * to get a specific image type (e.g. a pattern) rather than the default one.
+ *
+ * @param[out] image_data Image from sensor. Buffer must be allocated by
+ * caller with size FP_SENSOR_IMAGE_SIZE.
+ * @param mode  enum fp_capture_type
+ *
+ * @return 0 on success
+ * @return negative value on error
  */
 int fp_sensor_acquire_image_with_mode(uint8_t *image_data, int mode);