Add KDoc to the services/analyticsproviders API interfaces

Document AnalyticsProvider, AnalyticsTransaction, AnalyticsTracker and
ErrorTracker at the interface level, and add the missing @param entries.

The provider doc records that providers are driven by the analytics service and
only receive data once the user has consented, and that startTransaction returns
null on a provider with no performance support.

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

services/analyticsproviders/api/src/main/kotlin/io/element/android/services/analyticsproviders/api/AnalyticsProvider.kt

@@ -11,15 +11,29 @@ package io.element.android.services.analyticsproviders.api
 import io.element.android.services.analyticsproviders.api.trackers.AnalyticsTracker
 import io.element.android.services.analyticsproviders.api.trackers.ErrorTracker
 
+/**
+ * One analytics backend, such as PostHog or Sentry.
+ *
+ * Providers are driven by the analytics service rather than used directly, and only receive data once the user has consented.
+ */
 interface AnalyticsProvider : AnalyticsTracker, ErrorTracker {
     /**
      * User friendly name.
      */
     val name: String
 
+    /** Starts the backend, to be called when the user consents to analytics. */
     fun init()
 
+    /** Stops the backend and drops any pending data, to be called when the user withdraws their consent. */
     fun stop()
 
+    /**
+     * Starts a performance transaction, returning `null` when this provider does not support them.
+     *
+     * @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?
 }

services/analyticsproviders/api/src/main/kotlin/io/element/android/services/analyticsproviders/api/AnalyticsTransaction.kt

@@ -9,6 +9,11 @@ package io.element.android.services.analyticsproviders.api
 
 import kotlin.time.Duration
 
+/**
+ * A performance measurement in progress, which reports its timing once [finish] is called.
+ *
+ * Transactions can nest through [startChild]; see `recordChildTransaction` for a scoped alternative that always finishes the child.
+ */
 interface AnalyticsTransaction {
     /**
      * The time elapsed since the transaction started until now if the transaction is ongoing or the time it finished.
@@ -17,11 +22,17 @@ interface AnalyticsTransaction {
 
     /**
      * Start a child span from this transaction.
+     *
+     * @param operation the kind of operation the child measures.
+     * @param description a human readable detail shown alongside the measurement.
      */
     fun startChild(operation: String, description: String? = null): AnalyticsTransaction
 
     /**
      * Adds extra data to the transaction. This data is not indexed, it's just listed.
+     *
+     * @param key the name of the field.
+     * @param value the value to attach.
      */
     fun putExtraData(key: String, value: String)
 
@@ -29,6 +40,9 @@ interface AnalyticsTransaction {
      * Similar to [putExtraData], adds extra data that *will be indexed* and can be used for filtering in the analytics portal.
      *
      * **Do not add numerical values using this function, use [putExtraData] instead.**
+     *
+     * @param key the name of the indexed field.
+     * @param value the value to attach.
      */
     fun putIndexableData(key: String, value: String)
 
@@ -44,6 +58,8 @@ interface AnalyticsTransaction {
 
     /**
      * Attach a throwable to the transaction, so we can know it failed.
+     *
+     * @param throwable the failure that occurred during the measured operation.
      */
     fun attachError(throwable: Throwable)
 

services/analyticsproviders/api/src/main/kotlin/io/element/android/services/analyticsproviders/api/trackers/AnalyticsTracker.kt

@@ -14,19 +14,28 @@ import im.vector.app.features.analytics.plan.Interaction
 import im.vector.app.features.analytics.plan.SuperProperties
 import im.vector.app.features.analytics.plan.UserProperties
 
+/**
+ * Records analytics events; implemented by every provider and by the analytics service that fans out to them.
+ */
 interface AnalyticsTracker {
     /**
      * Capture an Event.
+     *
+     * @param event the event to record, taken from the shared analytics plan.
      */
     fun capture(event: VectorAnalyticsEvent)
 
     /**
      * Track a displayed screen.
+     *
+     * @param screen the screen that was shown.
      */
     fun screen(screen: VectorAnalyticsScreen)
 
     /**
      * Update user specific properties.
+     *
+     * @param userProperties the properties to merge into the current user's profile.
      */
     fun updateUserProperties(userProperties: UserProperties)
 

services/analyticsproviders/api/src/main/kotlin/io/element/android/services/analyticsproviders/api/trackers/ErrorTracker.kt

@@ -8,6 +8,14 @@
 
 package io.element.android.services.analyticsproviders.api.trackers
 
+/**
+ * Reports non-fatal errors to the crash reporting backend.
+ */
 interface ErrorTracker {
+    /**
+     * Records an error that was handled but is still worth knowing about.
+     *
+     * @param throwable the failure to report; never pass one whose message can contain user content.
+     */
     fun trackError(throwable: Throwable)
 }