From 437b93cc18751777e92f7a249dd67c93460382e0 Mon Sep 17 00:00:00 2001
From: Benoit Marty <benoitm@matrix.org>
Date: Wed, 4 Jan 2023 11:35:04 +0100
Subject: [PATCH] Add some doc

---
 .../internal/crypto/store/IMXCryptoStore.kt   | 19 +++++++++++++++++++
 .../internal/crypto/store/UserDataToStore.kt  |  6 ++++++
 2 files changed, 25 insertions(+)

diff --git a/matrix-sdk-android/src/main/java/org/matrix/android/sdk/internal/crypto/store/IMXCryptoStore.kt b/matrix-sdk-android/src/main/java/org/matrix/android/sdk/internal/crypto/store/IMXCryptoStore.kt
index 4ffd93875b..a74a7f2906 100644
--- a/matrix-sdk-android/src/main/java/org/matrix/android/sdk/internal/crypto/store/IMXCryptoStore.kt
+++ b/matrix-sdk-android/src/main/java/org/matrix/android/sdk/internal/crypto/store/IMXCryptoStore.kt
@@ -48,7 +48,19 @@ import org.matrix.olm.OlmOutboundGroupSession
  */
 internal interface IMXCryptoStore {
 
+    /**
+     * Notify the store that a sync response treatment is starting.
+     * Impacted methods:
+     * - [setShouldShareHistory]
+     * - [setShouldEncryptForInvitedMembers]
+     * @See [onSyncCompleted] to notify that the treatment is over.
+     */
     fun onSyncWillProcess()
+
+    /**
+     * Notify the store that the sync treatment response is finished.
+     * The store will save all aggregated data.
+     */
     fun onSyncCompleted()
 
     /**
@@ -291,6 +303,9 @@ internal interface IMXCryptoStore {
 
     fun shouldEncryptForInvitedMembers(roomId: String): Boolean
 
+    /**
+     * The data is not stored immediately, this MUST be call during a sync response treatment.
+     */
     fun setShouldEncryptForInvitedMembers(roomId: String, shouldEncryptForInvitedMembers: Boolean)
 
     fun shouldShareHistory(roomId: String): Boolean
@@ -298,6 +313,7 @@ internal interface IMXCryptoStore {
     /**
      * Sets a boolean flag that will determine whether or not room history (existing inbound sessions)
      * will be shared to new user invites.
+     * The data is not stored immediately, this MUST be call during a sync response treatment.
      *
      * @param roomId the room id
      * @param shouldShareHistory The boolean flag
@@ -582,5 +598,8 @@ internal interface IMXCryptoStore {
     fun tidyUpDataBase()
     fun getOutgoingRoomKeyRequests(inStates: Set<OutgoingRoomKeyRequestState>): List<OutgoingKeyRequest>
 
+    /**
+     * Store a bunch of data related to the users. @See [UserDataToStore].
+     */
     fun storeUserDataToStore(userDataToStore: UserDataToStore)
 }
diff --git a/matrix-sdk-android/src/main/java/org/matrix/android/sdk/internal/crypto/store/UserDataToStore.kt b/matrix-sdk-android/src/main/java/org/matrix/android/sdk/internal/crypto/store/UserDataToStore.kt
index d4b8308650..89cbe4e826 100644
--- a/matrix-sdk-android/src/main/java/org/matrix/android/sdk/internal/crypto/store/UserDataToStore.kt
+++ b/matrix-sdk-android/src/main/java/org/matrix/android/sdk/internal/crypto/store/UserDataToStore.kt
@@ -20,6 +20,12 @@ import org.matrix.android.sdk.api.session.crypto.crosssigning.CryptoCrossSigning
 import org.matrix.android.sdk.api.session.crypto.model.CryptoDeviceInfo
 
 internal data class UserDataToStore(
+        /**
+         * Map of userId -> (Map of deviceId -> [CryptoDeviceInfo]).
+         */
         val userDevices: MutableMap<String, Map<String, CryptoDeviceInfo>> = mutableMapOf(),
+        /**
+         * Map of userId -> [CryptoCrossSigningKeys].
+         */
         val userCrossSigningKeys: MutableMap<String, CryptoCrossSigningKeys> = mutableMapOf(),
 )