Add KDoc to the libraries/usersearch API interfaces

Document UserRepository and UserListDataSource along with their members.

Two behaviours from MatrixUserRepository and MatrixUserListDataSource are recorded
because callers rely on them: the data source swallows a failed directory request
into an empty list, and a query that is a well-formed user id other than the
current user's yields that user even when the directory does not know them.

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

libraries/usersearch/api/src/main/kotlin/io/element/android/libraries/usersearch/api/UserListDataSource.kt

@@ -11,8 +11,24 @@ package io.element.android.libraries.usersearch.api
 import io.element.android.libraries.matrix.api.core.UserId
 import io.element.android.libraries.matrix.api.user.MatrixUser
 
+/**
+ * Low-level access to the homeserver's user directory; see [UserRepository] for the search used by the UI.
+ */
 interface UserListDataSource {
+    /**
+     * Searches the user directory, returning an empty list rather than failing when the request does not succeed.
+     *
+     * @param query the text to look for in user ids and display names.
+     * @param count the maximum number of results to return.
+     */
     // TODO should probably have a flow
     suspend fun search(query: String, count: Long): List<MatrixUser>
+
+    /**
+     * Fetches one user's profile.
+     *
+     * @param userId the user whose profile is requested.
+     * @return the profile, or `null` when it could not be retrieved.
+     */
     suspend fun getProfile(userId: UserId): MatrixUser?
 }

libraries/usersearch/api/src/main/kotlin/io/element/android/libraries/usersearch/api/UserRepository.kt

@@ -10,6 +10,15 @@ package io.element.android.libraries.usersearch.api
 
 import kotlinx.coroutines.flow.Flow
 
+/**
+ * Searches for users to start a conversation with or invite, combining the homeserver directory with what the app already knows.
+ */
 interface UserRepository {
+    /**
+     * Runs a search and emits its progress, so the UI can show local results before the directory answers.
+     * A query that is a well-formed user id other than the current user's also yields that user, even when the directory does not know them.
+     *
+     * @param query the text typed by the user.
+     */
     fun search(query: String): Flow<UserSearchResultState>
 }