From 6446b30255c173a0a8a0b2bdeb2a2b58789ed687 Mon Sep 17 00:00:00 2001
From: Benoit Marty <benoit@matrix.org>
Date: Fri, 14 Aug 2026 10:28:48 +0200
Subject: [PATCH] Add KDoc to the `libraries/eventformatter` API interfaces

Document RoomLatestEventFormatter, TimelineEventFormatter and
PinnedMessagesBannerFormatter along with their members.

The formatters return a nullable CharSequence, so each one now states what null
means: the event is not rendered as text at all.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../api/PinnedMessagesBannerFormatter.kt       |  6 ++++++
 .../api/RoomLatestEventFormatter.kt            | 18 ++++++++++++++++++
 .../api/TimelineEventFormatter.kt              | 16 ++++++++++++++++
 3 files changed, 40 insertions(+)

diff --git a/libraries/eventformatter/api/src/main/kotlin/io/element/android/libraries/eventformatter/api/PinnedMessagesBannerFormatter.kt b/libraries/eventformatter/api/src/main/kotlin/io/element/android/libraries/eventformatter/api/PinnedMessagesBannerFormatter.kt
index 67994f18b9..986e5dfe32 100644
--- a/libraries/eventformatter/api/src/main/kotlin/io/element/android/libraries/eventformatter/api/PinnedMessagesBannerFormatter.kt
+++ b/libraries/eventformatter/api/src/main/kotlin/io/element/android/libraries/eventformatter/api/PinnedMessagesBannerFormatter.kt
@@ -10,6 +10,12 @@ package io.element.android.libraries.eventformatter.api
 
 import io.element.android.libraries.matrix.api.timeline.item.event.EventTimelineItem
 
+/**
+ * Formats the short summary of a pinned event shown in the banner at the top of a room.
+ */
 interface PinnedMessagesBannerFormatter {
+    /**
+     * @param event the pinned event to describe.
+     */
     fun format(event: EventTimelineItem): CharSequence
 }
diff --git a/libraries/eventformatter/api/src/main/kotlin/io/element/android/libraries/eventformatter/api/RoomLatestEventFormatter.kt b/libraries/eventformatter/api/src/main/kotlin/io/element/android/libraries/eventformatter/api/RoomLatestEventFormatter.kt
index abb5cc929d..7ddc65f57b 100644
--- a/libraries/eventformatter/api/src/main/kotlin/io/element/android/libraries/eventformatter/api/RoomLatestEventFormatter.kt
+++ b/libraries/eventformatter/api/src/main/kotlin/io/element/android/libraries/eventformatter/api/RoomLatestEventFormatter.kt
@@ -10,7 +10,25 @@ package io.element.android.libraries.eventformatter.api
 
 import io.element.android.libraries.matrix.api.roomlist.LatestEventValue
 
+/**
+ * Formats the one-line preview of a room's latest event, as shown in the room list.
+ */
 interface RoomLatestEventFormatter {
+    /**
+     * Formats an event that is still local, i.e. queued or being sent.
+     *
+     * @param latestEvent the local event to describe.
+     * @param isDmRoom whether the room is a direct message, which lets the sender name be left out.
+     * @return the preview text, or `null` when this kind of event should not be previewed.
+     */
     fun format(latestEvent: LatestEventValue.Local, isDmRoom: Boolean): CharSequence?
+
+    /**
+     * Formats an event that has been received from the server.
+     *
+     * @param latestEvent the remote event to describe.
+     * @param isDmRoom whether the room is a direct message, which lets the sender name be left out.
+     * @return the preview text, or `null` when this kind of event should not be previewed.
+     */
     fun format(latestEvent: LatestEventValue.Remote, isDmRoom: Boolean): CharSequence?
 }
diff --git a/libraries/eventformatter/api/src/main/kotlin/io/element/android/libraries/eventformatter/api/TimelineEventFormatter.kt b/libraries/eventformatter/api/src/main/kotlin/io/element/android/libraries/eventformatter/api/TimelineEventFormatter.kt
index be601fb82a..37081be242 100644
--- a/libraries/eventformatter/api/src/main/kotlin/io/element/android/libraries/eventformatter/api/TimelineEventFormatter.kt
+++ b/libraries/eventformatter/api/src/main/kotlin/io/element/android/libraries/eventformatter/api/TimelineEventFormatter.kt
@@ -13,7 +13,16 @@ import io.element.android.libraries.matrix.api.timeline.item.event.EventContent
 import io.element.android.libraries.matrix.api.timeline.item.event.EventTimelineItem
 import io.element.android.libraries.matrix.api.timeline.item.event.getDisambiguatedDisplayName
 
+/**
+ * Turns a state or membership event into the human readable sentence shown in the timeline, such as "Alice joined the room".
+ */
 interface TimelineEventFormatter {
+    /**
+     * Convenience overload that reads the sender and ownership from the timeline item itself.
+     *
+     * @param event the timeline item to describe.
+     * @return the sentence to display, or `null` when this kind of event is not rendered as text.
+     */
     fun format(event: EventTimelineItem): CharSequence? {
         return format(
             content = event.content,
@@ -22,5 +31,12 @@ interface TimelineEventFormatter {
             senderDisambiguatedDisplayName = event.senderProfile.getDisambiguatedDisplayName(event.sender),
         )
     }
+    /**
+     * @param content the event content to describe.
+     * @param isOutgoing whether the event was sent by the current user, which selects the first-person wording.
+     * @param sender the user who sent the event.
+     * @param senderDisambiguatedDisplayName the sender's display name, already suffixed with their id when it is ambiguous in the room.
+     * @return the sentence to display, or `null` when this kind of event is not rendered as text.
+     */
     fun format(content: EventContent, isOutgoing: Boolean, sender: UserId, senderDisambiguatedDisplayName: String): CharSequence?
 }