diff --git a/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/AcquiredInfo.aidl b/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/AcquiredInfo.aidl
index 8cb7833..a3259f6 100644
--- a/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/AcquiredInfo.aidl
+++ b/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/AcquiredInfo.aidl
@@ -19,13 +19,49 @@
 @VintfStability
 @Backing(type="byte")
 enum AcquiredInfo {
+    /**
+     * A high quality fingerprint image was detected, no further user interaction is necessary.
+     */
     GOOD,
+
+    /**
+     * Not enough of a fingerprint was detected. Reposition the finger, or a longer swipe needed.
+     */
     PARTIAL,
+
+    /**
+     * Image doesn't contain enough detail for recognition.
+     */
     INSUFFICIENT,
+
+    /**
+     * The sensor needs to be cleaned.
+     */
     SENSOR_DIRTY,
+
+    /**
+     * For swipe-type sensors, the swipe was too slow and not enough data was collected.
+     */
     TOO_SLOW,
+
+    /**
+     * For swipe-type sensors, the swipe was too fast and not enough data was collected.
+     */
     TOO_FAST,
+
+    /**
+     * This message represents the earliest message sent at the beginning of the authentication
+     * pipeline. It is expected to be used to measure latency. For example, in a camera-based
+     * authentication system it's expected to be sent prior to camera initialization. Note this
+     * should be sent whenever authentication is started or restarted. The framework may measure
+     * latency based on the time between the last START message and the onAuthenticated callback.
+     */
     START,
+
+    /**
+     * Vendor-specific acquisition message. See ISessionCallback#onAcquired vendorCode
+     * documentation.
+     */
     VENDOR
 }
 
diff --git a/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/ILockoutCallback.aidl b/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/ILockoutCallback.aidl
index 4b31a38..43cb20f 100644
--- a/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/ILockoutCallback.aidl
+++ b/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/ILockoutCallback.aidl
@@ -22,9 +22,9 @@
      * Notifies the framework that the user has just entered the Error::LOCKOUT state. This must be
      * sent in the following scenarios:
      * 1) The user just attempted authentication and was rejected, resulting in a timed lockout.
-     * 2) The framework just created a session for a sensorId/userId pair that has not been
+     * 2) The framework just created a session for a (sensorId, userId) pair that has not been
      *    created since the HAL started (e.g. there is no active or idle session for this
-     *    sensorId/userId pair.
+     *    (sensorId, userId) pair.
      *
      * @param sensorId Sensor for which the user is locked out.
      * @param userId User for which the sensor is locked out.
@@ -36,9 +36,9 @@
      * Notifies the framework that the user has just entered the Error::LOCKOUT_PERMANENT state.
      * This must be sent in the following scenarios:
      * 1) The user just attempted authentication and was rejected, resulting in a permanent lockout.
-     * 2) The framework just created a session for a sensorId/userId pair that has not been
+     * 2) The framework just created a session for a (sensorId, userId) pair that has not been
      *    created since the HAL started (e.g. there is no active or idle session for this
-     *    sensorId/userId pair.
+     *    (sensorId, userId) pair.
      *
      * @param sensorId Sensor for which the user is locked out.
      * @param userId User for which the sensor is locked out.
@@ -46,11 +46,13 @@
     void onLockoutPermanent(in int sensorId, in int userId);
 
     /**
-     * Notifies the framework that lockout has been cleared for this sensorId/userId pair. This
+     * Notifies the framework that lockout has been cleared for this (sensorId, userId) pair. This
      * can happen in the following scenarios:
      * 1) A timed lockout has ended (e.g. original durationMillis specified in #onLockoutTimed
      *    has expired.
      * 2) See ISession#resetLockout.
+     * 3) The (sensorId, userId) pair is not in any lockout state, and the user successfully
+     *    authenticated with a fingerprint.
      *
      * @param sensorId Sensor for which the user's lockout is cleared.
      * @param userId User for the sensor's lockout is cleared.
diff --git a/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/ISession.aidl b/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/ISession.aidl
index 5fa56e0..946027b 100644
--- a/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/ISession.aidl
+++ b/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/ISession.aidl
@@ -80,7 +80,7 @@
      *
      * When a finger is successfully added and before the framework is notified
      * of remaining=0, the implementation MUST update and associate this
-     * (sensorId, user) pair with a new new entropy-encoded random identifier.
+     * (sensorId, userId) pair with a new new entropy-encoded random identifier.
      * See ISession#getAuthenticatorId for more information.
      *
      * @param cookie An identifier used to track subsystem operations related
@@ -147,10 +147,75 @@
      */
     ICancellationSignal authenticate(in int cookie, in long operationId);
 
+    /**
+     * detectInteraction:
+     *
+     * A request to start looking for fingerprints without performing matching.
+     *
+     * Once the HAL is able to start processing this request, it must notify the framework via
+     * ISessionCallback#onStateChanged with SessionState::DETECTING_INTERACTION.
+     *
+     * The framework will use this method in cases where determing user presence is required, but
+     * identifying/authentication is not. For example, when the device is encrypted (first boot) or
+     * in lockdown mode.
+     *
+     * At any point during detectInteraction, if a non-recoverable error occurs, the HAL must notify
+     * the framework via ISessionCallback#onError with the applicable error, and then send
+     * ISessionCallback#onStateChanged(cookie, SessionState::IDLING) if no subsequent operation is
+     * in the queue.
+     *
+     * The implementation must only check for a fingerprint-like image was detected (e.g. to
+     * minimize interactions due to non-fingerprint objects), and the lockout counter must not
+     * be modified.
+     *
+     * Upon detecting any fingerprint, the implementation must invoke
+     * ISessionCallback#onInteractionDetected.
+     *
+     * The lifecycle of this operation ends when either
+     * 1) Any fingerprint is detected and the framework is notified via
+     *    ISessionCallback#onInteractiondetected
+     * 2) The operation was cancelled by the framework (see ICancellationSignal)
+     * 3) The HAL ends the operation, for example when a subsequent operation pre-empts this one.
+     *
+     * Note that if the operation is canceled, the implementation must notify the framework via
+     * ISessionCallback#onError with Error::CANCELED.
+     *
+     * @param cookie An identifier used to track subsystem operations related to this call path.
+     *               The framework will guarantee that it is unique per ISession.
+     */
     ICancellationSignal detectInteraction(in int cookie);
 
+    /*
+     * enumerateEnrollments:
+     *
+     * A request to enumerate (list) the enrollments for this (sensorId, userId) pair. The
+     * framework typically uses this to ensure that its cache is in sync with the HAL.
+     *
+     * Once the HAL is able to start processing this request, it must notify the framework via
+     * ISessionCallback#onStateChanged with SessionState::ENUMERATING_ENROLLMENTS.
+     *
+     * The implementation must then notify the framework with a list of enrollments applicable
+     * for the current session via ISessionCallback#onEnrollmentsEnumerated.
+     *
+     * @param cookie An identifier used to track subsystem operations related to this call path.
+     *               The framework will guarantee that it is unique per ISession.
+     */
     void enumerateEnrollments(in int cookie);
 
+    /**
+     * removeEnrollments:
+     *
+     * A request to remove the enrollments for this (sensorId, userId) pair.
+     *
+     * Once the HAL is able to start processing this request, it must notify the framework via
+     * ISessionCallback#onStateChanged with SessionState::REMOVING_ENROLLMENTS.
+     *
+     * After removing the enrollmentIds from everywhere necessary (filesystem, secure subsystems,
+     * etc), the implementation must notify the framework via ISessionCallback#onEnrollmentsRemoved.
+     *
+     * @param cookie An identifier used to track subsystem operations related to this call path.
+     *               The framework will guarantee that it is unique per ISession.
+     */
     void removeEnrollments(in int cookie, in int[] enrollmentIds);
 
     /**
@@ -259,10 +324,54 @@
      * Methods for notifying the under-display fingerprint sensor about external events.
      */
 
+    /**
+     * onPointerDown:
+     *
+     * This method only applies to sensors that are configured as
+     * FingerprintSensorType::UNDER_DISPLAY_*. If invoked erroneously by the framework for sensors
+     * of other types, the HAL must treat this as a no-op and return immediately.
+     *
+     * For sensors of type FingerprintSensorType::UNDER_DISPLAY_*, this method is used to notify the
+     * HAL of display touches. This method can be invoked when the session is in one of the
+     * following states: SessionState::ENROLLING, SessionState::AUTHENTICATING, or
+     * SessionState::DETECTING_INTERACTION.
+     *
+     * Note that the framework will only invoke this method if the event occurred on the display
+     * on which this sensor is located.
+     *
+     * Note that for sensors which require illumination such as
+     * FingerprintSensorType::UNDER_DISPLAY_OPTICAL, and where illumination is handled below
+     * the framework, this is a good time to start illuminating.
+     *
+     * @param pointerId See android.view.MotionEvent#getPointerId
+     * @param x The distance in pixels from the left edge of the display.
+     * @param y The distance in pixels from the top edge of the display.
+     * @param minor See android.view.MotionEvent#getTouchMinor
+     * @param major See android.view.MotionEvent#getTouchMajor
+     */
     void onPointerDown(in int pointerId, in int x, in int y, in float minor, in float major);
 
+    /**
+     * onPointerUp:
+     *
+     * This method only applies to sensors that are configured as
+     * FingerprintSensorType::UNDER_DISPLAY_*. If invoked for sensors of other types, the HAL must
+     * treat this as a no-op and return immediately.
+     *
+     * @param pointerId See android.view.MotionEvent#getPointerId
+     */
     void onPointerUp(in int pointerId);
 
+    /*
+     * onUiReady:
+     *
+     * This method only applies to sensors that are configured as
+     * FingerprintSensorType::UNDER_DISPLAY_OPTICAL. If invoked for sensors of other types, the HAL
+     * must treat this as a no-op and return immediately.
+     *
+     * For FingerprintSensorType::UNDER_DISPLAY_OPTICAL where illumination is handled above the
+     * HAL, the framework will invoke this method to notify that the illumination has started.
+     */
     void onUiReady();
 }
 
diff --git a/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/ISessionCallback.aidl b/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/ISessionCallback.aidl
index 7130520..81a87a8 100644
--- a/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/ISessionCallback.aidl
+++ b/biometrics/fingerprint/aidl/android/hardware/biometrics/fingerprint/ISessionCallback.aidl
@@ -23,14 +23,48 @@
 
 @VintfStability
 interface ISessionCallback {
+    /**
+     * Used to notify the framework of session state changes. See ISession for more information.
+     */
     void onStateChanged(in int cookie, in SessionState state);
 
+    /**
+     * This method must only be used to notify the framework during the following states:
+     *   1) SessionState::ENROLLING
+     *   2) SessionState::AUTHENTICATING
+     *   3) SessionState::DETECTING_INTERACTION
+     *
+     * These messages may be used to provide user guidance multiple times if necessary per
+     * operation.
+     *
+     * @param info See the AcquiredInfo enum.
+     * @param vendorCode Only valid if info == AcquiredInfo::VENDOR.
+     */
     void onAcquired(in AcquiredInfo info, in int vendorCode);
 
+    /**
+     * This method must only be used to notify the framework during the following states:
+     *   1) SessionState::ENROLLING
+     *   2) SessionState::AUTHENTICATING
+     *   3) SessionState::DETECTING_INTERACTION
+     *   4) SessionState::INVALIDATING_AUTHENTICATOR_ID
+     *   5) SessionState::RESETTING_LOCKOUT
+     *
+     * These messages may be used to notify the framework or user that a non-recoverable error
+     * has occurred. The operation is finished, and the HAL must proceed with the next operation
+     * or return to SessionState::IDLING if the queue is empty.
+     *
+     * Note that cancellation (see common::ICancellationSignal) and preemption most be followed with
+     * an Error::CANCELED message.
+     *
+     * @param error See the Error enum.
+     * @param vendorCode Only valid if error == Error::VENDOR.
+     */
     void onError(in Error error, in int vendorCode);
 
     /**
-     * Used to notify the framework of enrollment progress. Enrollment completes when remaining==0,
+     * This method must only be used to notify the framework during the following state:
+     *   1) SessionState::ENROLLING
      *
      * @param enrollmentId Unique stable identifier for the enrollment that's being added by this
      *                     ISession#enroll invocation.
@@ -39,6 +73,8 @@
     void onEnrollmentProgress(in int enrollmentId, int remaining);
 
     /**
+     * This method must only be used to notify the framework during SessionState::AUTHENTICATING.
+     *
      * Used to notify the framework upon successful authentication. Note that the authentication
      * lifecycle ends when either 1) a fingerprint is accepted, or 2) an error such as
      * Error::LOCKOUT occurred. The authentication lifecycle does NOT end when a fingerprint is
@@ -53,6 +89,8 @@
     void onAuthenticationSucceeded(in int enrollmentId, in HardwareAuthToken hat);
 
     /**
+     * This method must only be used to notify the framework during SessionState::AUTHENTICATING.
+     *
      * Used to notify the framework upon rejected attempts. Note that the authentication
      * lifecycle ends when either 1) a fingerprint is accepted, or 2) an error such as
      * Error::LOCKOUT occurred. The authentication lifecycle does NOT end when a fingerprint is
@@ -60,19 +98,50 @@
      */
     void onAuthenticationFailed();
 
+    /**
+     * This method must only be used to notify the framework during
+     * SessionState::DETECTING_INTERACTION
+     *
+     * Notifies the framework that user interaction occurred. See ISession#detectInteraction.
+     */
     void onInteractionDetected();
 
+    /**
+     * This method must only be used to notify the framework during
+     * SessionState::ENUMERATING_ENROLLMENTS.
+     *
+     * Notifies the framework of the current enrollments. See ISession#enumerateEnrollments.
+     *
+     * @param enrollmentIds A list of enrollments for the session's (userId, sensorId) pair.
+     */
     void onEnrollmentsEnumerated(in int[] enrollmentIds);
 
+    /**
+     * This method must only be used to notify the framework during
+     * SessionState::REMOVING_ENROLLMENTS.
+     *
+     * Notifies the framework that the specified enrollments are removed.
+     *
+     * @param enrollmentIds The enrollments that were removed.
+     */
     void onEnrollmentsRemoved(in int[] enrollmentIds);
 
     /**
-     * A callback invoked when ISession#getAuthenticatorId is invoked.
+     * This method must only be used to notify the framework during
+     * SessionState::GETTING_AUTHENTICATOR_ID.
+     *
+     * Notifies the framework with the authenticatorId corresponding to this session's
+     * (userId, sensorId) pair.
+     *
+     * @param authenticatorId See the above documentation.
      */
     void onAuthenticatorIdRetrieved(in long authenticatorId);
 
     /**
-     * A callback invoked when ISession#invalidateAuthenticatorId has completed.
+     * This method must only be used to notify the framework during
+     * SessionState::INVALIDATING_AUTHENTICATOR_ID.
+     *
+     * See ISession#invalidateAuthenticatorId for more information.
      */
     void onAuthenticatorIdInvalidated();
 }