From 57658640e1a5116ff9b676f812518ab13f3167b6 Mon Sep 17 00:00:00 2001 From: Benoit Marty Date: Fri, 14 Aug 2026 11:48:58 +0200 Subject: [PATCH] Add KDoc to the `features/location` API interfaces Document LocationService, StaticMapUrlBuilder, TileServerStyleUriBuilder and the members of ActiveLiveLocationShareManager that had none. The two URL builders now say what happens when no map provider is configured for the build, which is the case LocationService.isServiceAvailable exists to guard. Co-Authored-By: Claude Opus 5 (1M context) --- .../android/features/location/api/LocationService.kt | 4 ++++ .../location/api/internal/StaticMapUrlBuilder.kt | 12 ++++++++++++ .../api/internal/TileServerStyleUriBuilder.kt | 6 ++++++ .../api/live/ActiveLiveLocationShareManager.kt | 10 ++++++++++ 4 files changed, 32 insertions(+) diff --git a/features/location/api/src/main/kotlin/io/element/android/features/location/api/LocationService.kt b/features/location/api/src/main/kotlin/io/element/android/features/location/api/LocationService.kt index 22049c9548..41c58c396f 100644 --- a/features/location/api/src/main/kotlin/io/element/android/features/location/api/LocationService.kt +++ b/features/location/api/src/main/kotlin/io/element/android/features/location/api/LocationService.kt @@ -8,6 +8,10 @@ package io.element.android.features.location.api +/** + * Tells whether the location features can be used at all, which depends on the build having a map provider configured. + */ interface LocationService { + /** Whether location sharing and map rendering are available; `false` disables the whole feature in the UI. */ fun isServiceAvailable(): Boolean } diff --git a/features/location/api/src/main/kotlin/io/element/android/features/location/api/internal/StaticMapUrlBuilder.kt b/features/location/api/src/main/kotlin/io/element/android/features/location/api/internal/StaticMapUrlBuilder.kt index 6636976828..c03fb8a838 100644 --- a/features/location/api/src/main/kotlin/io/element/android/features/location/api/internal/StaticMapUrlBuilder.kt +++ b/features/location/api/src/main/kotlin/io/element/android/features/location/api/internal/StaticMapUrlBuilder.kt @@ -12,6 +12,17 @@ package io.element.android.features.location.api.internal * Builds an URL for a 3rd party service provider static maps API. */ interface StaticMapUrlBuilder { + /** + * Builds the URL of a map image centred on the given coordinates. + * + * @param lat latitude of the centre of the map. + * @param lon longitude of the centre of the map. + * @param zoom zoom level to render at. + * @param darkMode whether to request the dark map style. + * @param width width of the image in density independent pixels. + * @param height height of the image in density independent pixels. + * @param density screen density, used to request a matching pixel size. + */ fun build( lat: Double, lon: Double, @@ -22,6 +33,7 @@ interface StaticMapUrlBuilder { density: Float, ): String + /** Whether a map provider is configured for this build; the URLs are unusable when it is not. */ fun isServiceAvailable(): Boolean } diff --git a/features/location/api/src/main/kotlin/io/element/android/features/location/api/internal/TileServerStyleUriBuilder.kt b/features/location/api/src/main/kotlin/io/element/android/features/location/api/internal/TileServerStyleUriBuilder.kt index 762d580f8e..08a40d2a7b 100644 --- a/features/location/api/src/main/kotlin/io/element/android/features/location/api/internal/TileServerStyleUriBuilder.kt +++ b/features/location/api/src/main/kotlin/io/element/android/features/location/api/internal/TileServerStyleUriBuilder.kt @@ -18,6 +18,12 @@ import io.element.android.compound.theme.ElementTheme * Used for rendering dynamic maps. */ interface TileServerStyleUriBuilder { + /** + * Builds the style URI the map view loads its tiles from. + * + * @param customMapStyleUrl the style advertised by the homeserver, or `null` to use the one built into the app. + * @param darkMode whether to request the dark map style. + */ fun build( customMapStyleUrl: String?, darkMode: Boolean, diff --git a/features/location/api/src/main/kotlin/io/element/android/features/location/api/live/ActiveLiveLocationShareManager.kt b/features/location/api/src/main/kotlin/io/element/android/features/location/api/live/ActiveLiveLocationShareManager.kt index cd6b8731c1..74c9089c30 100644 --- a/features/location/api/src/main/kotlin/io/element/android/features/location/api/live/ActiveLiveLocationShareManager.kt +++ b/features/location/api/src/main/kotlin/io/element/android/features/location/api/live/ActiveLiveLocationShareManager.kt @@ -12,6 +12,9 @@ import io.element.android.libraries.matrix.api.core.RoomId import kotlinx.coroutines.flow.StateFlow import kotlin.time.Duration +/** + * Owns the live location shares running on this device, across every room, and the foreground service that feeds them GPS updates. + */ interface ActiveLiveLocationShareManager { /** All rooms currently sharing live location on this device. */ val sharingRoomIds: StateFlow> @@ -28,6 +31,10 @@ interface ActiveLiveLocationShareManager { * Calls room.startLiveLocationShare() on the SDK, registers the share, * and starts the foreground GPS service if not already running. */ + /** + * @param roomId the room to start sharing the location in. + * @param duration how long the share should last before it expires on its own. + */ suspend fun startShare(roomId: RoomId, duration: Duration): Result /** @@ -35,6 +42,9 @@ interface ActiveLiveLocationShareManager { * Calls room.stopLiveLocationShare() on the SDK, removes the share, * and stops the foreground service if no shares remain. */ + /** + * @param roomId the room to stop sharing the location in. + */ suspend fun stopShare(roomId: RoomId): Result }