diff --git a/libraries/matrix/api/src/main/kotlin/io/element/android/libraries/matrix/api/room/MatrixRoom.kt b/libraries/matrix/api/src/main/kotlin/io/element/android/libraries/matrix/api/room/MatrixRoom.kt
index 86e943fea9..fc4ded247a 100644
--- a/libraries/matrix/api/src/main/kotlin/io/element/android/libraries/matrix/api/room/MatrixRoom.kt
+++ b/libraries/matrix/api/src/main/kotlin/io/element/android/libraries/matrix/api/room/MatrixRoom.kt
@@ -98,8 +98,15 @@ interface MatrixRoom : Closeable {
 
     val syncUpdateFlow: StateFlow<Long>
 
+    /**
+     * The live timeline of the room. Must be used to send Event to a room.
+     */
     val liveTimeline: Timeline
 
+    /**
+     * Create a new timeline, focused on the provided Event.
+     * Should not be used directly, see `TimelineController` to manage the various timelines.
+     */
     suspend fun timelineFocusedOnEvent(eventId: EventId): Result<Timeline>
 
     fun destroy()