From bc6f237507b38fcf5e91769f3f60664fe04dc5b8 Mon Sep 17 00:00:00 2001
From: Benoit Marty <benoit@matrix.org>
Date: Fri, 14 Aug 2026 10:04:31 +0200
Subject: [PATCH] Add KDoc to the `features/invitepeople` API interfaces

Document InvitePeopleState and each of its properties, InvitePeopleEvents,
InvitePeopleRenderer and the presenter factory.

The state properties now say what drives them, in particular that
createRoomFromDmAction covers the case of inviting a third person into an
existing direct message, and that the factory accepts a null room for that flow.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../features/invitepeople/api/InvitePeopleEvents.kt  |  3 +++
 .../invitepeople/api/InvitePeoplePresenter.kt        |  7 +++++++
 .../invitepeople/api/InvitePeopleRenderer.kt         |  9 +++++++++
 .../features/invitepeople/api/InvitePeopleState.kt   | 12 ++++++++++++
 4 files changed, 31 insertions(+)

diff --git a/features/invitepeople/api/src/main/kotlin/io/element/android/features/invitepeople/api/InvitePeopleEvents.kt b/features/invitepeople/api/src/main/kotlin/io/element/android/features/invitepeople/api/InvitePeopleEvents.kt
index 0422fac4f1..9570ab8152 100644
--- a/features/invitepeople/api/src/main/kotlin/io/element/android/features/invitepeople/api/InvitePeopleEvents.kt
+++ b/features/invitepeople/api/src/main/kotlin/io/element/android/features/invitepeople/api/InvitePeopleEvents.kt
@@ -8,6 +8,9 @@
 
 package io.element.android.features.invitepeople.api
 
+/**
+ * Events the invite people UI sends to its presenter through [InvitePeopleState.eventSink].
+ */
 interface InvitePeopleEvents {
     data object SendInvites : InvitePeopleEvents
     data object CloseSearch : InvitePeopleEvents
diff --git a/features/invitepeople/api/src/main/kotlin/io/element/android/features/invitepeople/api/InvitePeoplePresenter.kt b/features/invitepeople/api/src/main/kotlin/io/element/android/features/invitepeople/api/InvitePeoplePresenter.kt
index 0be0798680..1863397e48 100644
--- a/features/invitepeople/api/src/main/kotlin/io/element/android/features/invitepeople/api/InvitePeoplePresenter.kt
+++ b/features/invitepeople/api/src/main/kotlin/io/element/android/features/invitepeople/api/InvitePeoplePresenter.kt
@@ -13,7 +13,14 @@ import io.element.android.libraries.matrix.api.core.RoomId
 import io.element.android.libraries.matrix.api.room.JoinedRoom
 
 interface InvitePeoplePresenter : Presenter<InvitePeopleState> {
+    /**
+     * Creates a presenter for one invite flow.
+     */
     interface Factory {
+        /**
+         * @param joinedRoom the room to invite into, or `null` when the room does not exist yet, as when inviting from a direct message.
+         * @param roomId the id of the room to invite into.
+         */
         fun create(
             joinedRoom: JoinedRoom?,
             roomId: RoomId,
diff --git a/features/invitepeople/api/src/main/kotlin/io/element/android/features/invitepeople/api/InvitePeopleRenderer.kt b/features/invitepeople/api/src/main/kotlin/io/element/android/features/invitepeople/api/InvitePeopleRenderer.kt
index 7bad81ab65..0bbaa45a2f 100644
--- a/features/invitepeople/api/src/main/kotlin/io/element/android/features/invitepeople/api/InvitePeopleRenderer.kt
+++ b/features/invitepeople/api/src/main/kotlin/io/element/android/features/invitepeople/api/InvitePeopleRenderer.kt
@@ -11,7 +11,16 @@ package io.element.android.features.invitepeople.api
 import androidx.compose.runtime.Composable
 import androidx.compose.ui.Modifier
 
+/**
+ * Renders the invite people UI, so that other screens can embed it without depending on its implementation.
+ */
 interface InvitePeopleRenderer {
+    /**
+     * Draws the invite list and its search field.
+     *
+     * @param state the state produced by [InvitePeoplePresenter].
+     * @param modifier layout modifier for the container.
+     */
     @Composable
     fun Render(
         state: InvitePeopleState,
diff --git a/features/invitepeople/api/src/main/kotlin/io/element/android/features/invitepeople/api/InvitePeopleState.kt b/features/invitepeople/api/src/main/kotlin/io/element/android/features/invitepeople/api/InvitePeopleState.kt
index d14042cff7..0863ec7212 100644
--- a/features/invitepeople/api/src/main/kotlin/io/element/android/features/invitepeople/api/InvitePeopleState.kt
+++ b/features/invitepeople/api/src/main/kotlin/io/element/android/features/invitepeople/api/InvitePeopleState.kt
@@ -11,10 +11,22 @@ package io.element.android.features.invitepeople.api
 import io.element.android.libraries.architecture.AsyncAction
 import io.element.android.libraries.matrix.api.core.RoomId
 
+/**
+ * State of the invite people UI, produced by an [InvitePeoplePresenter] and consumed by an [InvitePeopleRenderer].
+ */
 interface InvitePeopleState {
+    /** Whether the send button should be enabled, i.e. at least one user is selected and the user has the permission. */
     val canInvite: Boolean
+
+    /** Whether the search field currently has focus, which the host screen uses to adapt its own layout. */
     val isSearchActive: Boolean
+
+    /** Progress of the invite request, so the UI can show a loader and surface failures. */
     val sendInvitesAction: AsyncAction<Unit>
+
+    /** Progress of turning a direct message into a room, which happens when inviting a third person into a DM. */
     val createRoomFromDmAction: AsyncAction<RoomId>
+
+    /** Where the UI sends its events. */
     val eventSink: (InvitePeopleEvents) -> Unit
 }