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

Document PollContentStateFactory, SendPollResponseAction and EndPollAction along
with their members and parameters.

The two action interfaces exist to wrap a plain timeline call, so their docs say
what they add: both capture an analytics event on success, which is the reason
callers should go through them rather than calling the timeline directly.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../features/poll/api/actions/EndPollAction.kt    |  7 +++++++
 .../poll/api/actions/SendPollResponseAction.kt    |  8 ++++++++
 .../api/pollcontent/PollContentStateFactory.kt    | 15 +++++++++++++++
 3 files changed, 30 insertions(+)

diff --git a/features/poll/api/src/main/kotlin/io/element/android/features/poll/api/actions/EndPollAction.kt b/features/poll/api/src/main/kotlin/io/element/android/features/poll/api/actions/EndPollAction.kt
index a46a2db781..b33a00c165 100644
--- a/features/poll/api/src/main/kotlin/io/element/android/features/poll/api/actions/EndPollAction.kt
+++ b/features/poll/api/src/main/kotlin/io/element/android/features/poll/api/actions/EndPollAction.kt
@@ -11,6 +11,13 @@ package io.element.android.features.poll.api.actions
 import io.element.android.libraries.matrix.api.core.EventId
 import io.element.android.libraries.matrix.api.timeline.Timeline
 
+/**
+ * Closes a poll so no further answers are accepted, wrapping the timeline call so the analytics are captured in one place.
+ */
 interface EndPollAction {
+    /**
+     * @param timeline the timeline the poll lives in.
+     * @param pollStartId the poll start event to close.
+     */
     suspend fun execute(timeline: Timeline, pollStartId: EventId): Result<Unit>
 }
diff --git a/features/poll/api/src/main/kotlin/io/element/android/features/poll/api/actions/SendPollResponseAction.kt b/features/poll/api/src/main/kotlin/io/element/android/features/poll/api/actions/SendPollResponseAction.kt
index 00b60ed5ae..cbaace50fb 100644
--- a/features/poll/api/src/main/kotlin/io/element/android/features/poll/api/actions/SendPollResponseAction.kt
+++ b/features/poll/api/src/main/kotlin/io/element/android/features/poll/api/actions/SendPollResponseAction.kt
@@ -11,7 +11,15 @@ package io.element.android.features.poll.api.actions
 import io.element.android.libraries.matrix.api.core.EventId
 import io.element.android.libraries.matrix.api.timeline.Timeline
 
+/**
+ * Sends the current user's answer to a poll, wrapping the timeline call so the analytics are captured in one place.
+ */
 interface SendPollResponseAction {
+    /**
+     * @param timeline the timeline the poll lives in.
+     * @param pollStartId the poll start event being answered.
+     * @param answerId the id of the chosen answer.
+     */
     suspend fun execute(
         timeline: Timeline,
         pollStartId: EventId,
diff --git a/features/poll/api/src/main/kotlin/io/element/android/features/poll/api/pollcontent/PollContentStateFactory.kt b/features/poll/api/src/main/kotlin/io/element/android/features/poll/api/pollcontent/PollContentStateFactory.kt
index c9bd31ea4f..87e3f5eece 100644
--- a/features/poll/api/src/main/kotlin/io/element/android/features/poll/api/pollcontent/PollContentStateFactory.kt
+++ b/features/poll/api/src/main/kotlin/io/element/android/features/poll/api/pollcontent/PollContentStateFactory.kt
@@ -12,7 +12,16 @@ import io.element.android.libraries.matrix.api.core.EventId
 import io.element.android.libraries.matrix.api.timeline.item.event.EventTimelineItem
 import io.element.android.libraries.matrix.api.timeline.item.event.PollContent
 
+/**
+ * Turns the poll content of a timeline event into the state the poll UI renders.
+ */
 interface PollContentStateFactory {
+    /**
+     * Convenience overload that reads the editability and ownership from the timeline item itself.
+     *
+     * @param eventTimelineItem the timeline item carrying the poll.
+     * @param content the poll content of that item.
+     */
     suspend fun create(eventTimelineItem: EventTimelineItem, content: PollContent): PollContentState {
         return create(
             eventId = eventTimelineItem.eventId,
@@ -21,5 +30,11 @@ interface PollContentStateFactory {
             content = content,
         )
     }
+    /**
+     * @param eventId the poll start event, or `null` while the poll is still a local echo.
+     * @param isEditable whether the current user may still edit the poll.
+     * @param isOwn whether the poll was created by the current user.
+     * @param content the poll question, answers and votes.
+     */
     suspend fun create(eventId: EventId?, isEditable: Boolean, isOwn: Boolean, content: PollContent): PollContentState
 }