code review: renaming, comments, extract common code

libraries/matrix/api/src/main/kotlin/io/element/android/libraries/matrix/api/encryption/EncryptionService.kt

@@ -66,7 +66,15 @@ interface EncryptionService {
      * Remember this identity, ensuring it does not result in a pin violation.
      */
     suspend fun pinUserIdentity(userId: UserId): Result<Unit>
-    suspend fun withdrawVerificationRequirement(userId: UserId): Result<Unit>
+
+    /**
+     * Withdraw the verification for that user (also pin the identity).
+     *
+     * Useful when a user that was verified is not anymore, but it is not
+     * possible to re-verify immediately. This allows to restore communication by reverting the
+     * user trust from verified to TOFU verified.
+     */
+    suspend fun withdrawVerification(userId: UserId): Result<Unit>
 }
 
 /**