Add KDoc to the services/analytics API interfaces

Document AnalyticsService and ScreenTracker at the interface level, document the
members of the cold start and room list watchers, and add the missing @param
entries across the analytics interfaces.

The AnalyticsService doc states the rule that applies to the whole interface:
nothing reaches the providers until the user has given their consent.

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

services/analytics/api/src/main/kotlin/io/element/android/services/analytics/api/AnalyticsSdkManager.kt

@@ -13,16 +13,23 @@ package io.element.android.services.analytics.api
 interface AnalyticsSdkManager {
     /**
      * Enable or disable SDK analytics.
+     *
+     * @param enabled true to let the SDK report analytics, normally following the user consent.
      */
     fun enableSdkAnalytics(enabled: Boolean)
 
     /**
      * Start a new span with the given [name], using [parentTraceId] to optionally attach it to a parent transaction.
+     *
+     * @param name the name of the span.
+     * @param parentTraceId the trace to attach the span to, or `null` to start a root span.
      */
     fun startSpan(name: String, parentTraceId: String? = null): AnalyticsSdkSpan
 
     /**
      * Create a 'bridge' span optionally linking it to a parent trace via [parentTraceId].
+     *
+     * @param parentTraceId the trace to link the bridge to, or `null` to leave it unattached.
      */
     fun bridge(parentTraceId: String? = null): AnalyticsSdkSpan
 }

services/analytics/api/src/main/kotlin/io/element/android/services/analytics/api/AnalyticsService.kt

@@ -15,6 +15,11 @@ import io.element.android.services.analyticsproviders.api.trackers.AnalyticsTrac
 import io.element.android.services.analyticsproviders.api.trackers.ErrorTracker
 import kotlinx.coroutines.flow.Flow
 
+/**
+ * Central analytics entry point: user consent, the analytics identity, and performance transactions.
+ *
+ * Nothing is sent to the providers until the user has given their consent through [setUserConsent].
+ */
 interface AnalyticsService : AnalyticsTracker, ErrorTracker {
     /**
      * Get the available analytics providers.
@@ -28,6 +33,8 @@ interface AnalyticsService : AnalyticsTracker, ErrorTracker {
 
     /**
      * Update the user consent value.
+     *
+     * @param userConsent true when the user agrees to analytics being collected.
      */
     suspend fun setUserConsent(userConsent: Boolean)
 
@@ -48,16 +55,26 @@ interface AnalyticsService : AnalyticsTracker, ErrorTracker {
 
     /**
      * Update analyticsId from the AccountData.
+     *
+     * @param analyticsId the identifier shared across the user's clients, so their events are attributed to one person.
      */
     suspend fun setAnalyticsId(analyticsId: String)
 
     /**
      * Starts a transaction to measure the performance of an operation.
+     * The caller is responsible for finishing it; see `recordTransaction` for a scoped alternative.
+     *
+     * @param name the name the transaction is reported under.
+     * @param operation the kind of operation being measured.
+     * @param description a human readable detail shown alongside the measurement.
      */
     fun startTransaction(name: String, operation: String? = null, description: String? = null): AnalyticsTransaction
 
     /**
      * Starts an [AnalyticsLongRunningTransaction], that can be shared with other components.
+     *
+     * @param longRunningTransaction which of the known long running operations is starting.
+     * @param parentTransaction the transaction to attach this one to, or `null` to start a root transaction.
      */
     fun startLongRunningTransaction(
         longRunningTransaction: AnalyticsLongRunningTransaction,
@@ -66,15 +83,25 @@ interface AnalyticsService : AnalyticsTracker, ErrorTracker {
 
     /**
      * Gets an ongoing [AnalyticsLongRunningTransaction], if it exists.
+     *
+     * @param longRunningTransaction the long running operation to look up.
      */
     fun getLongRunningTransaction(longRunningTransaction: AnalyticsLongRunningTransaction): AnalyticsTransaction?
 
     /**
      * Removes an ongoing [AnalyticsLongRunningTransaction] so it's no longer shared.
+     *
+     * @param longRunningTransaction the long running operation to stop sharing.
+     * @return the transaction that was removed, or `null` when none was ongoing.
      */
     fun removeLongRunningTransaction(longRunningTransaction: AnalyticsLongRunningTransaction): AnalyticsTransaction?
 
-    /** Enter a span inside the Rust SDK tracing system. If a [parentTraceId] is provided, the SDK trace will be added as a child of that trace. */
+    /**
+     * Enter a span inside the Rust SDK tracing system. If a [parentTraceId] is provided, the SDK trace will be added as a child of that trace.
+     *
+     * @param name the name of the span.
+     * @param parentTraceId the trace to attach the span to, or `null` to start a root span.
+     */
     @Discouraged("This method can cause crashes of the app when using debug builds of the Rust SDK.")
     fun enterSdkSpan(name: String?, parentTraceId: String?): AnalyticsSdkSpan
 }

services/analytics/api/src/main/kotlin/io/element/android/services/analytics/api/ScreenTracker.kt

@@ -11,7 +11,15 @@ package io.element.android.services.analytics.api
 import androidx.compose.runtime.Composable
 import im.vector.app.features.analytics.plan.MobileScreen
 
+/**
+ * Reports screen views to analytics from Composable code.
+ */
 interface ScreenTracker {
+    /**
+     * Records a view of [screen] when this enters composition, so it is called once per appearance rather than on every recomposition.
+     *
+     * @param screen the screen being shown.
+     */
     @Composable
     fun TrackScreen(
         screen: MobileScreen.ScreenName,

services/analytics/api/src/main/kotlin/io/element/android/services/analytics/api/watchers/AnalyticsColdStartWatcher.kt

@@ -12,7 +12,12 @@ package io.element.android.services.analytics.api.watchers
  * until the cached room list is displayed. This check only takes place in a cold app start after the user is authenticated.
  */
 interface AnalyticsColdStartWatcher {
+    /** Begins the measurement, to be called as early as possible in the cold start. */
     fun start()
+
+    /** Restarts the measurement from the login flow, since a user who has to sign in first is not a normal cold start. */
     fun whenLoggingIn()
+
+    /** Ends the measurement, to be called once the cached room list is actually on screen. */
     fun onRoomListVisible()
 }

services/analytics/api/src/main/kotlin/io/element/android/services/analytics/api/watchers/AnalyticsRoomListStateWatcher.kt

@@ -12,6 +12,9 @@ package io.element.android.services.analytics.api.watchers
  * the app was previously running and we just returned to it.
  */
 interface AnalyticsRoomListStateWatcher {
+    /** Begins watching the room list state, to be called when the app returns to the foreground. */
     fun start()
+
+    /** Stops watching, to be called when the app leaves the foreground. */
     fun stop()
 }