From 4a5d0d2540f2c3ec6fce8303a184b80c768f0b79 Mon Sep 17 00:00:00 2001 From: Benoit Marty Date: Fri, 14 Aug 2026 10:31:34 +0200 Subject: [PATCH] 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) --- .../analyticsproviders/api/AnalyticsProvider.kt | 14 ++++++++++++++ .../api/AnalyticsTransaction.kt | 16 ++++++++++++++++ .../api/trackers/AnalyticsTracker.kt | 9 +++++++++ .../api/trackers/ErrorTracker.kt | 8 ++++++++ 4 files changed, 47 insertions(+) diff --git a/services/analyticsproviders/api/src/main/kotlin/io/element/android/services/analyticsproviders/api/AnalyticsProvider.kt b/services/analyticsproviders/api/src/main/kotlin/io/element/android/services/analyticsproviders/api/AnalyticsProvider.kt index 593d62f40f..7b6278740c 100644 --- a/services/analyticsproviders/api/src/main/kotlin/io/element/android/services/analyticsproviders/api/AnalyticsProvider.kt +++ b/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? } diff --git a/services/analyticsproviders/api/src/main/kotlin/io/element/android/services/analyticsproviders/api/AnalyticsTransaction.kt b/services/analyticsproviders/api/src/main/kotlin/io/element/android/services/analyticsproviders/api/AnalyticsTransaction.kt index 82d337914a..f54cadbda8 100644 --- a/services/analyticsproviders/api/src/main/kotlin/io/element/android/services/analyticsproviders/api/AnalyticsTransaction.kt +++ b/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) diff --git a/services/analyticsproviders/api/src/main/kotlin/io/element/android/services/analyticsproviders/api/trackers/AnalyticsTracker.kt b/services/analyticsproviders/api/src/main/kotlin/io/element/android/services/analyticsproviders/api/trackers/AnalyticsTracker.kt index 5bb63338a8..db4a8a5517 100644 --- a/services/analyticsproviders/api/src/main/kotlin/io/element/android/services/analyticsproviders/api/trackers/AnalyticsTracker.kt +++ b/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) diff --git a/services/analyticsproviders/api/src/main/kotlin/io/element/android/services/analyticsproviders/api/trackers/ErrorTracker.kt b/services/analyticsproviders/api/src/main/kotlin/io/element/android/services/analyticsproviders/api/trackers/ErrorTracker.kt index 5277493b64..94a04b842b 100644 --- a/services/analyticsproviders/api/src/main/kotlin/io/element/android/services/analyticsproviders/api/trackers/ErrorTracker.kt +++ b/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) }