diff --git a/libraries/matrix/api/src/main/kotlin/io/element/android/libraries/matrix/api/HomeserverCapabilitiesProvider.kt b/libraries/matrix/api/src/main/kotlin/io/element/android/libraries/matrix/api/HomeserverCapabilitiesProvider.kt
index e914656f5f..fe05b88dc4 100644
--- a/libraries/matrix/api/src/main/kotlin/io/element/android/libraries/matrix/api/HomeserverCapabilitiesProvider.kt
+++ b/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 {
diff --git a/libraries/matrix/api/src/main/kotlin/io/element/android/libraries/matrix/api/MatrixClientProvider.kt b/libraries/matrix/api/src/main/kotlin/io/element/android/libraries/matrix/api/MatrixClientProvider.kt
index 54f70845fa..08073d0cc0 100644
--- a/libraries/matrix/api/src/main/kotlin/io/element/android/libraries/matrix/api/MatrixClientProvider.kt
+++ b/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?
 }
diff --git a/libraries/matrix/api/src/main/kotlin/io/element/android/libraries/matrix/api/SdkMetadata.kt b/libraries/matrix/api/src/main/kotlin/io/element/android/libraries/matrix/api/SdkMetadata.kt
index 16f34807fc..939734e314 100644
--- a/libraries/matrix/api/src/main/kotlin/io/element/android/libraries/matrix/api/SdkMetadata.kt
+++ b/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
 }
diff --git a/libraries/matrix/api/src/main/kotlin/io/element/android/libraries/matrix/api/TemporaryMatrixClientFactory.kt b/libraries/matrix/api/src/main/kotlin/io/element/android/libraries/matrix/api/TemporaryMatrixClientFactory.kt
index 4be1b980a0..3bd22c64f3 100644
--- a/libraries/matrix/api/src/main/kotlin/io/element/android/libraries/matrix/api/TemporaryMatrixClientFactory.kt
+++ b/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>
 }
diff --git a/libraries/matrix/api/src/main/kotlin/io/element/android/libraries/matrix/api/sync/SyncService.kt b/libraries/matrix/api/src/main/kotlin/io/element/android/libraries/matrix/api/sync/SyncService.kt
index ce0019d8dc..92f60352d7 100644
--- a/libraries/matrix/api/src/main/kotlin/io/element/android/libraries/matrix/api/sync/SyncService.kt
+++ b/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>
 }