Add KDoc to the remaining matrix API interfaces

Document the permalink, widget, tracing, core, platform, server and analytics
interfaces along with their members, which completes libraries/matrix/api: all
69 in-scope interfaces and their 398 members now carry documentation.

Notable points recorded here: PermalinkParser reports an unrecognised uri as a
fallback link rather than failing, MatrixWidgetDriver.run is a no-op while it is
already running and send is silently ignored once closed, and every member of
CallAnalyticCredentialsProvider is null when the service is unconfigured or the
user has not consented to analytics.

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

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

@@ -9,6 +9,14 @@ package io.element.android.libraries.matrix.api.analytics
 
 import io.element.android.libraries.matrix.api.core.SessionId
 
+/**
+ * Reads the on-disk size of a session's SDK stores, so they can be reported as analytics.
+ */
 fun interface GetDatabaseSizesUseCase {
+    /**
+     * Returns the size of each store of the given session.
+     *
+     * @param sessionId the session whose stores are measured.
+     */
     operator fun invoke(sessionId: SessionId): Result<SdkStoreSizes>
 }

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

@@ -8,6 +8,15 @@
 
 package io.element.android.libraries.matrix.api.core
 
+/**
+ * Reports the progress of a long running transfer, such as a media upload or download.
+ */
 interface ProgressCallback {
+    /**
+     * Called as the transfer advances, possibly many times and from a background thread.
+     *
+     * @param current the number of bytes transferred so far.
+     * @param total the total number of bytes to transfer.
+     */
     fun onProgress(current: Long, total: Long)
 }

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

@@ -8,6 +8,10 @@
 
 package io.element.android.libraries.matrix.api.core
 
+/**
+ * A handle on an event sitting in a room's send queue, obtained from a timeline item that failed to send.
+ */
 fun interface SendHandle {
+    /** Puts the event back in the send queue for another attempt. */
     suspend fun retry(): Result<Unit>
 }

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

@@ -20,6 +20,9 @@ interface MatrixToConverter {
      * - https://riot.im/develop/#/room/#element-android:matrix.org  ->  https://matrix.to/#/#element-android:matrix.org
      * - https://app.element.io/#/room/#element-android:matrix.org   ->  https://matrix.to/#/#element-android:matrix.org
      * - https://www.example.org/#/room/#element-android:matrix.org  ->  https://matrix.to/#/#element-android:matrix.org
+     *
+     * @param uri the uri to convert.
+     * @return the equivalent matrix.to uri, or `null` when the input is not a permalink this converter recognises.
      */
     fun convert(uri: Uri): Uri?
 }

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

@@ -11,8 +11,22 @@ package io.element.android.libraries.matrix.api.permalink
 import io.element.android.libraries.matrix.api.core.RoomAlias
 import io.element.android.libraries.matrix.api.core.UserId
 
+/**
+ * Builds `matrix.to` permalinks, which are the shareable links to a user or a room; see [PermalinkParser] for the other direction.
+ */
 interface PermalinkBuilder {
+    /**
+     * Builds a permalink to a user, failing with [PermalinkBuilderError.InvalidData] when the id is malformed.
+     *
+     * @param userId the user to link to.
+     */
     fun permalinkForUser(userId: UserId): Result<String>
+
+    /**
+     * Builds a permalink to a room from its alias, failing with [PermalinkBuilderError.InvalidData] when the alias is malformed.
+     *
+     * @param roomAlias the room alias to link to.
+     */
     fun permalinkForRoomAlias(roomAlias: RoomAlias): Result<String>
 }
 

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

@@ -18,7 +18,10 @@ package io.element.android.libraries.matrix.api.permalink
 interface PermalinkParser {
     /**
      * Turns a uri string to a [PermalinkData].
+     * A uri that is not a Matrix permalink is reported as a fallback link rather than as an error, so this never throws.
      * https://github.com/matrix-org/matrix-doc/blob/master/proposals/1704-matrix.to-permalinks.md
+     *
+     * @param uriString the uri to parse.
      */
     fun parse(uriString: String): PermalinkData
 }

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

@@ -8,6 +8,10 @@
 
 package io.element.android.libraries.matrix.api.server
 
+/**
+ * Resolves the server name of the logged in user, which is the part of their user id after the colon.
+ */
 interface UserServerResolver {
+    /** Returns the server name, for instance `matrix.org` for `@alice:matrix.org`. */
     fun resolve(): String
 }

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

@@ -10,8 +10,21 @@ package io.element.android.libraries.matrix.api.tracing
 
 import timber.log.Timber
 
+/**
+ * Routes the app's own logs into the SDK's tracing subsystem, so that Kotlin and Rust logs end up interleaved in the same files.
+ */
 interface TracingService {
+    /**
+     * Creates a Timber tree that forwards what the app logs to the SDK tracing subsystem.
+     *
+     * @param target the tracing target name the logs are attributed to, used to tell subsystems apart in the output.
+     */
     fun createTimberTree(target: String): Timber.Tree
 
+    /**
+     * Turns writing logs to files on or off at runtime, which is how the user-facing logging toggle is applied.
+     *
+     * @param config where to write the log files, or the disabled configuration to stop writing them.
+     */
     fun updateWriteToFilesConfiguration(config: WriteToFilesConfiguration)
 }

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

@@ -8,10 +8,24 @@
 
 package io.element.android.libraries.matrix.api.widget
 
+/**
+ * Supplies the analytics and crash reporting credentials passed to the embedded Element Call widget.
+ *
+ * Every member is `null` when the corresponding service is not configured for this build, or when the user has not consented to analytics.
+ */
 interface CallAnalyticCredentialsProvider {
+    /** The PostHog identifier of the current user, so call analytics can be tied to the same person as app analytics. */
     val posthogUserId: String?
+
+    /** The PostHog host the widget should send its events to. */
     val posthogApiHost: String?
+
+    /** The PostHog API key the widget should use. */
     val posthogApiKey: String?
+
+    /** The URL the widget should submit its rageshakes to. */
     val rageshakeSubmitUrl: String?
+
+    /** The Sentry DSN the widget should report its crashes to. */
     val sentryDsn: String?
 }

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

@@ -10,7 +10,18 @@ package io.element.android.libraries.matrix.api.widget
 
 import java.util.UUID
 
+/**
+ * Builds the widget settings used to embed Element Call in a room, applying the app's own preferences on top of the SDK defaults.
+ */
 interface CallWidgetSettingsProvider {
+    /**
+     * @param baseUrl the URL Element Call is served from.
+     * @param widgetId a unique identifier for this widget instance.
+     * @param encrypted whether the room the call takes place in is encrypted.
+     * @param direct whether the call happens in a direct message room.
+     * @param isAudioCall whether the call should start without video.
+     * @param hasActiveCall whether a call is already ongoing in the room, which affects whether the user joins straight away.
+     */
     suspend fun provide(
         baseUrl: String,
         widgetId: String = UUID.randomUUID().toString(),

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

@@ -10,10 +10,25 @@ package io.element.android.libraries.matrix.api.widget
 
 import kotlinx.coroutines.flow.Flow
 
+/**
+ * Bridges a widget running in a WebView with the Matrix room it is embedded in, relaying the widget API messages in both directions.
+ *
+ * The driver owns SDK resources and must be closed once the widget goes away; Element Call is the main user of this.
+ */
 interface MatrixWidgetDriver : AutoCloseable {
+    /** The id of the widget this driver serves, matching the one in its settings. */
     val id: String
+
+    /** The messages coming from the room that should be forwarded to the widget. */
     val incomingMessages: Flow<String>
 
+    /** Starts relaying messages and suspends for as long as the driver runs; calling it again while it is running does nothing. */
     suspend fun run()
+
+    /**
+     * Forwards a message from the widget to the room. Does nothing once the driver has been closed.
+     *
+     * @param message the raw widget API message emitted by the WebView.
+     */
     suspend fun send(message: String)
 }