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>
 }