Add KDoc to matrix API session and sync interfaces

Document MatrixClientProvider, SdkMetadata, HomeserverCapabilitiesProvider,
TemporaryMatrixClientFactory and SyncService, along with each of their members.

Behaviour described here was checked against the implementations
(MatrixSessionCache, RustSdkMetadata, RustHomeserverCapabilitiesProvider,
RustTemporaryMatrixClientFactory and RustSyncService), so the docs mention the
caching, idempotence and error-wrapping that callers cannot infer from the
signatures alone.

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

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

@@ -10,6 +10,8 @@ package io.element.android.libraries.matrix.api
 /**
  * Provides information about the capabilities of the homeserver.
  *
+ * The getters read a snapshot held by the SDK rather than querying the server on each call, so [refresh] must be used to pick up server-side changes.
+ *
  * Spec: https://spec.matrix.org/latest/client-server-api/#capabilities-negotiation
  */
 interface HomeserverCapabilitiesProvider {

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

@@ -10,18 +10,26 @@ package io.element.android.libraries.matrix.api
 
 import io.element.android.libraries.matrix.api.core.SessionId
 
+/**
+ * In-memory cache of the [MatrixClient] of every logged in session.
+ *
+ * Prefer injecting the [MatrixClient] directly: this provider is meant for the entry points that only know a [SessionId], such as push handling and workers.
+ */
 interface MatrixClientProvider {
     /**
-     * Can be used to get or restore a MatrixClient with the given [SessionId].
-     * If a [MatrixClient] is already in memory, it'll return it. Otherwise it'll try to restore one.
-     * Most of the time you want to use injected constructor instead of retrieving a MatrixClient with this provider.
+     * Returns the cached [MatrixClient] for [sessionId], restoring the session from storage and starting its sync if it is not in memory yet.
+     * Concurrent calls are serialised, so only one restore happens per session.
+     *
+     * @param sessionId the [SessionId] of the session to get or restore.
+     * @return the client, or a failure if the session could not be restored.
      */
     suspend fun getOrRestore(sessionId: SessionId): Result<MatrixClient>
 
     /**
-     * Can be used to retrieve an existing [MatrixClient] with the given [SessionId].
-     * @param sessionId the [SessionId] of the [MatrixClient] to retrieve.
-     * @return the [MatrixClient] if it exists.
+     * Returns the [MatrixClient] for [sessionId] only if it is already in memory, without attempting to restore it.
+     *
+     * @param sessionId the [SessionId] of the session to retrieve.
+     * @return the cached client, or `null` if that session is not currently held in memory.
      */
     fun getOrNull(sessionId: SessionId): MatrixClient?
 }

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

@@ -8,6 +8,14 @@
 
 package io.element.android.libraries.matrix.api
 
+/**
+ * Exposes build information about the bundled `matrix-rust-sdk`.
+ *
+ * Mostly used to identify the exact SDK revision in bug reports and in the user agent.
+ */
 interface SdkMetadata {
+    /**
+     * The full git SHA of the commit the bundled `matrix-rust-sdk` was built from.
+     */
     val sdkGitSha: String
 }

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

@@ -11,5 +11,11 @@ package io.element.android.libraries.matrix.api
  * Factory to create a temporary [TemporaryMatrixClient] for a given home server URL.
  */
 interface TemporaryMatrixClientFactory {
+    /**
+     * Builds an unauthenticated client pointing at [homeServerUrl], backed by a fresh set of temporary session directories.
+     * The caller owns the returned client and must close it to delete those directories.
+     *
+     * @param homeServerUrl the URL of the homeserver the client will talk to.
+     */
     suspend fun create(homeServerUrl: String): Result<TemporaryMatrixClient>
 }

libraries/matrix/api/src/main/kotlin/io/element/android/libraries/matrix/api/sync/SyncService.kt

@@ -10,21 +10,31 @@ package io.element.android.libraries.matrix.api.sync
 
 import kotlinx.coroutines.flow.StateFlow
 
+/**
+ * Drives the sync loop of a single session and exposes its current state.
+ *
+ * Both [startSync] and [stopSync] are idempotent and never throw: any error is wrapped in the returned [Result].
+ */
 interface SyncService {
     /**
-     * Tries to start the sync. If already syncing it has no effect.
+     * Tries to start the sync. If already syncing, or if the service has been destroyed, it has no effect.
      */
     suspend fun startSync(): Result<Unit>
 
     /**
-     * Tries to stop the sync. If service is not syncing it has no effect.
+     * Tries to stop the sync. If the service is not syncing, or has been destroyed, it has no effect.
      */
     suspend fun stopSync(): Result<Unit>
 
     /**
      * Flow of [SyncState]. Will be updated as soon as the current [SyncState] changes.
+     * Starts at [SyncState.Idle] and only emits on an actual change, for as long as the session lives.
      */
     val syncState: StateFlow<SyncState>
 
+    /**
+     * Whether the client currently considers itself online, derived from [syncState].
+     * This is `false` only while the state is [SyncState.Offline]; an idle or errored sync still counts as online.
+     */
     val isOnline: StateFlow<Boolean>
 }