Merge pull request #7426 from element-hq/feature/bma/documentation

Add KDoc to all the interfaces of the api modules

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
 }

features/location/api/src/main/kotlin/io/element/android/features/location/api/internal/StaticMapUrlBuilder.kt

@@ -16,6 +16,17 @@ import io.element.android.libraries.wellknown.api.MapTilerConfig
  * 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,
@@ -26,6 +37,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
 }
 

features/location/api/src/main/kotlin/io/element/android/features/location/api/internal/TileServerStyleUriBuilder.kt

@@ -19,6 +19,12 @@ import io.element.android.libraries.wellknown.api.MapTilerConfig
  * 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(
         customMapTilerConfig: MapTilerConfig?,
         darkMode: Boolean,

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<Set<RoomId>>
@@ -27,6 +30,9 @@ interface ActiveLiveLocationShareManager {
      * Starts live location sharing in the given room.
      * 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<Unit>
 
@@ -34,6 +40,8 @@ interface ActiveLiveLocationShareManager {
      * Stops live location sharing in the given room.
      * 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<Unit>
 }