Add KDoc to matrix API room list, directory and spaces interfaces

Document RoomDirectoryService, RoomDirectoryList, SpaceService, SpaceRoomList
and LeaveSpaceHandle along with their members, add the missing DynamicRoomList
page size doc and the missing @param entries, and give MessageSearchService the
interface level doc it was lacking.

The docs make the ownership rules explicit, since they differ across these
types: a SpaceRoomList and a LeaveSpaceHandle are owned by the caller and must be
destroyed or closed, while a RoomDirectoryList and a MessageSearch are released
when the scope they were created with completes.

RoomList, RoomListService and the search interfaces were already accurate and are
left untouched.

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

libraries/matrix/api/src/main/kotlin/io/element/android/libraries/matrix/api/roomdirectory/RoomDirectoryList.kt

@@ -10,12 +10,21 @@ package io.element.android.libraries.matrix.api.roomdirectory
 
 import kotlinx.coroutines.flow.Flow
 
+/**
+ * A single, stateful search in the public room directory: one query at a time, with paginated results.
+ *
+ * Obtain an instance from [RoomDirectoryService.createRoomDirectoryList].
+ */
 interface RoomDirectoryList {
     /**
      * Starts a filtered search for the server.
      * If the filter is not provided it will search for all the rooms. You can specify a batch_size to control the number of rooms to fetch per request.
      * If the via_server is not provided it will search in the current homeserver by default.
      * This method will clear the current search results and start a new one
+     *
+     * @param filter the text to look for, or `null` to list every room.
+     * @param batchSize the number of rooms to fetch per request.
+     * @param viaServerName the server whose directory to search, or `null` to use the user's own homeserver.
      */
     suspend fun filter(filter: String?, batchSize: Int, viaServerName: String?): Result<Unit>
 

libraries/matrix/api/src/main/kotlin/io/element/android/libraries/matrix/api/roomdirectory/RoomDirectoryService.kt

@@ -10,6 +10,14 @@ package io.element.android.libraries.matrix.api.roomdirectory
 
 import kotlinx.coroutines.CoroutineScope
 
+/**
+ * Gives access to the public room directory, i.e. the rooms a server advertises to users who have not joined them.
+ */
 interface RoomDirectoryService {
+    /**
+     * Creates an independent directory search, which is stateful and holds one query at a time.
+     *
+     * @param scope the lifetime of the search; the underlying SDK resources are released when it completes, so there is nothing to close by hand.
+     */
     fun createRoomDirectoryList(scope: CoroutineScope): RoomDirectoryList
 }

libraries/matrix/api/src/main/kotlin/io/element/android/libraries/matrix/api/roomlist/DynamicRoomList.kt

@@ -14,6 +14,7 @@ package io.element.android.libraries.matrix.api.roomlist
  * It lets load rooms on demand and filter them.
  */
 interface DynamicRoomList : RoomList {
+    /** The number of rooms added to the list by each [loadMore] call, as chosen when the list was created. */
     val pageSize: Int
 
     /**

libraries/matrix/api/src/main/kotlin/io/element/android/libraries/matrix/api/search/MessageSearchService.kt

@@ -10,6 +10,11 @@ package io.element.android.libraries.matrix.api.search
 import io.element.android.libraries.matrix.api.core.RoomId
 import kotlinx.coroutines.CoroutineScope
 
+/**
+ * Creates the message search cursors backed by the local search index.
+ *
+ * Only usable when the session was built with the index attached, see [io.element.android.libraries.matrix.api.MatrixClient.isMessageSearchAvailable].
+ */
 interface MessageSearchService {
     /**
      * Create a new, independent search cursor.

libraries/matrix/api/src/main/kotlin/io/element/android/libraries/matrix/api/spaces/LeaveSpaceHandle.kt

@@ -10,6 +10,11 @@ package io.element.android.libraries.matrix.api.spaces
 
 import io.element.android.libraries.matrix.api.core.RoomId
 
+/**
+ * Handles leaving a space, letting the user also choose which of its rooms to leave in the same operation.
+ *
+ * Obtain an instance from [SpaceService.getLeaveSpaceHandle]; the caller owns it and must [close] it.
+ */
 interface LeaveSpaceHandle {
     /**
      * The id of the space to leave.

libraries/matrix/api/src/main/kotlin/io/element/android/libraries/matrix/api/spaces/SpaceRoomList.kt

@@ -16,22 +16,36 @@ import kotlinx.coroutines.flow.launchIn
 import kotlinx.coroutines.flow.onEach
 import java.util.Optional
 
+/**
+ * The paginated list of the children of a single space, kept up to date by the SDK.
+ *
+ * Obtain an instance from [SpaceService.spaceRoomList]; the caller owns it and must call [destroy] when done.
+ */
 interface SpaceRoomList {
     sealed interface PaginationStatus {
         data object Loading : PaginationStatus
         data class Idle(val hasMoreToLoad: Boolean) : PaginationStatus
     }
 
+    /** The space whose children this list holds. */
     val spaceId: RoomId
 
+    /** What is known about the space itself, starting empty until the SDK provides it. */
     val currentSpaceFlow: StateFlow<Optional<SpaceRoom>>
 
+    /** The children loaded so far, re-emitted in full on every update; the latest value is replayed to new collectors. */
     val spaceRoomsFlow: Flow<List<SpaceRoom>>
+
+    /** Whether a page is being loaded and whether more children remain; see [loadAllIncrementally] to drain the list. */
     val paginationStatusFlow: StateFlow<PaginationStatus>
 
+    /** Loads the next page of children, which will be reflected in [spaceRoomsFlow]. */
     suspend fun paginate(): Result<Unit>
+
+    /** Discards the loaded children and starts the list again from the beginning. */
     suspend fun reset(): Result<Unit>
 
+    /** Releases the SDK resources and cancels the internal scope; the list is unusable afterwards. */
     fun destroy()
 }
 

libraries/matrix/api/src/main/kotlin/io/element/android/libraries/matrix/api/spaces/SpaceService.kt

@@ -11,13 +11,35 @@ package io.element.android.libraries.matrix.api.spaces
 import io.element.android.libraries.matrix.api.core.RoomId
 import kotlinx.coroutines.flow.SharedFlow
 
+/**
+ * Gives access to the spaces the user belongs to, their hierarchy, and the operations that change it.
+ */
 interface SpaceService {
+    /** The spaces that have no joined parent, i.e. the roots of the hierarchy shown to the user; the latest value is replayed to new collectors. */
     val topLevelSpacesFlow: SharedFlow<List<SpaceRoom>>
+
+    /** The filters the space list can be narrowed down with; as with [topLevelSpacesFlow], the latest value is replayed. */
     val spaceFiltersFlow: SharedFlow<List<SpaceServiceFilter>>
+
+    /**
+     * Returns the spaces the given room or space is a child of, restricted to the ones the user has joined.
+     *
+     * @param spaceId the room or space whose parents are requested.
+     */
     suspend fun joinedParents(spaceId: RoomId): Result<List<SpaceRoom>>
 
+    /**
+     * Returns what is known about a single space, or `null` if it is unknown or the lookup failed.
+     *
+     * @param spaceId the space to look up.
+     */
     suspend fun getSpaceRoom(spaceId: RoomId): SpaceRoom?
 
+    /**
+     * Creates a paginated list of the children of a space; the caller owns it and must call `destroy` on it.
+     *
+     * @param id the space whose children are listed.
+     */
     fun spaceRoomList(id: RoomId): SpaceRoomList
 
     /**
@@ -25,6 +47,11 @@ interface SpaceService {
      */
     suspend fun editableSpaces(): Result<List<SpaceRoom>>
 
+    /**
+     * Creates a handle to leave a space, which lets the user also pick which of its rooms to leave; the caller must close it.
+     *
+     * @param spaceId the space the user wants to leave.
+     */
     fun getLeaveSpaceHandle(spaceId: RoomId): LeaveSpaceHandle
 
     /**