From 1f3c73d3c6f0c4623df1af9836b6918202584618 Mon Sep 17 00:00:00 2001
From: Benoit Marty <benoit@matrix.org>
Date: Fri, 14 Aug 2026 10:28:56 +0200
Subject: [PATCH] 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>
---
 .../usersearch/api/UserListDataSource.kt         | 16 ++++++++++++++++
 .../libraries/usersearch/api/UserRepository.kt   |  9 +++++++++
 2 files changed, 25 insertions(+)

diff --git a/libraries/usersearch/api/src/main/kotlin/io/element/android/libraries/usersearch/api/UserListDataSource.kt b/libraries/usersearch/api/src/main/kotlin/io/element/android/libraries/usersearch/api/UserListDataSource.kt
index 0f7e02c7a8..9446668502 100644
--- a/libraries/usersearch/api/src/main/kotlin/io/element/android/libraries/usersearch/api/UserListDataSource.kt
+++ b/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?
 }
diff --git a/libraries/usersearch/api/src/main/kotlin/io/element/android/libraries/usersearch/api/UserRepository.kt b/libraries/usersearch/api/src/main/kotlin/io/element/android/libraries/usersearch/api/UserRepository.kt
index f7e5367a9a..b3be565ca5 100644
--- a/libraries/usersearch/api/src/main/kotlin/io/element/android/libraries/usersearch/api/UserRepository.kt
+++ b/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>
 }