Add KDoc to the libraries/pushstore API interfaces

Document UserPushStore, UserPushStoreFactory, PushClientSecret,
PushClientSecretStore and PushClientSecretFactory along with all their members.

The client secret interfaces now explain why they exist at all: a push gateway
delivers notifications without saying which account they belong to, so the secret
is what lets an incoming push be attributed back to a session.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

libraries/pushstore/api/src/main/kotlin/io/element/android/libraries/pushstore/api/UserPushStore.kt

@@ -13,15 +13,36 @@ import kotlinx.coroutines.flow.Flow
  * Store data related to push about a user.
  */
 interface UserPushStore {
+    /** The push provider selected for this user, or `null` when none has been selected yet. */
     suspend fun getPushProviderName(): String?
+
+    /**
+     * @param value the name of the push provider to remember for this user.
+     */
     suspend fun setPushProviderName(value: String)
+
+    /** The push key last registered with the homeserver, used to detect that a re-registration is needed; `null` when never registered. */
     suspend fun getCurrentRegisteredPushKey(): String?
+
+    /**
+     * @param value the push key that has just been registered, or `null` to forget it after unregistering.
+     */
     suspend fun setCurrentRegisteredPushKey(value: String?)
 
+    /** Whether the user has enabled notifications on this device. */
     fun getNotificationEnabledForDevice(): Flow<Boolean>
+
+    /**
+     * @param enabled true to enable notifications on this device.
+     */
     suspend fun setNotificationEnabledForDevice(enabled: Boolean)
 
+    /** Whether the user has asked not to be warned about pusher registration failures. */
     fun ignoreRegistrationError(): Flow<Boolean>
+
+    /**
+     * @param ignore true to stop warning the user about registration failures.
+     */
     suspend fun setIgnoreRegistrationError(ignore: Boolean)
 
     /**
@@ -29,5 +50,6 @@ interface UserPushStore {
      */
     fun useCompleteNotificationFormat(): Boolean
 
+    /** Erases every push preference of this user, to be called when their session is removed. */
     suspend fun reset()
 }

libraries/pushstore/api/src/main/kotlin/io/element/android/libraries/pushstore/api/UserPushStoreFactory.kt

@@ -14,5 +14,10 @@ import io.element.android.libraries.matrix.api.core.SessionId
  * Store data related to push about a user.
  */
 interface UserPushStoreFactory {
+    /**
+     * Returns the push store of a user, creating it on first use.
+     *
+     * @param userId the user whose store is requested.
+     */
     fun getOrCreate(userId: SessionId): UserPushStore
 }

libraries/pushstore/api/src/main/kotlin/io/element/android/libraries/pushstore/api/clientsecret/PushClientSecret.kt

@@ -10,15 +10,24 @@ package io.element.android.libraries.pushstore.api.clientsecret
 
 import io.element.android.libraries.matrix.api.core.SessionId
 
+/**
+ * Manages the per-session client secret sent along with a pusher registration.
+ *
+ * Push gateways deliver notifications without saying which account they belong to, so the secret is what lets an incoming push be attributed to a session.
+ */
 interface PushClientSecret {
     /**
      * To call when registering a pusher. It will return the existing secret or create a new one.
+     *
+     * @param userId the user the pusher is being registered for.
      */
     suspend fun getSecretForUser(userId: SessionId): String
 
     /**
      * To call when receiving a push containing a client secret.
      * Return null if not found.
+     *
+     * @param clientSecret the secret carried by the incoming push.
      */
     suspend fun getUserIdFromSecret(clientSecret: String): SessionId?
 }

libraries/pushstore/api/src/main/kotlin/io/element/android/libraries/pushstore/api/clientsecret/PushClientSecretFactory.kt

@@ -8,6 +8,10 @@
 
 package io.element.android.libraries.pushstore.api.clientsecret
 
+/**
+ * Generates the client secrets used to attribute an incoming push to a session; see [PushClientSecret] for how they are used.
+ */
 interface PushClientSecretFactory {
+    /** Returns a new random secret. */
     fun create(): String
 }

libraries/pushstore/api/src/main/kotlin/io/element/android/libraries/pushstore/api/clientsecret/PushClientSecretStore.kt

@@ -10,9 +10,37 @@ package io.element.android.libraries.pushstore.api.clientsecret
 
 import io.element.android.libraries.matrix.api.core.SessionId
 
+/**
+ * Persists the mapping between sessions and their push client secrets, in both directions.
+ */
 interface PushClientSecretStore {
+    /**
+     * Stores the secret of a user, replacing any previous one.
+     *
+     * @param userId the user the secret belongs to.
+     * @param clientSecret the secret to store.
+     */
     suspend fun storeSecret(userId: SessionId, clientSecret: String)
+
+    /**
+     * Returns the stored secret of a user, or `null` when they have none yet.
+     *
+     * @param userId the user whose secret is requested.
+     */
     suspend fun getSecret(userId: SessionId): String?
+
+    /**
+     * Forgets the secret of a user, to be called when their session is removed.
+     *
+     * @param userId the user whose secret is erased.
+     */
     suspend fun resetSecret(userId: SessionId)
+
+    /**
+     * Reverse lookup used when a push arrives carrying only a secret.
+     *
+     * @param clientSecret the secret to resolve.
+     * @return the user it belongs to, or `null` when no session matches.
+     */
     suspend fun getUserIdFromSecret(clientSecret: String): SessionId?
 }