Better document the various protocols and classes involved in dealing with room timelines.

Author: stefanceriu

ElementX/Sources/Screens/Timeline/TimelineInteractionHandler.swift

@@ -26,6 +26,8 @@ enum TimelineInteractionHandlerAction {
     case viewInRoomTimeline(eventID: String)
 }
 
+/// The interaction handler groups logic for dealing with various actions the user can take on a timeline's
+/// view that would've normally been part of the ``TimelineViewModel``
 @MainActor
 class TimelineInteractionHandler {
     private let roomProxy: JoinedRoomProxyProtocol

ElementX/Sources/Services/Timeline/TimelineController/TimelineControllerProtocol.swift

@@ -33,6 +33,11 @@ enum TimelineControllerError: Error {
     case eventNotFound
 }
 
+/// This protocol is a high level abstraction on top of the ``TimelineProxyProtocol``
+/// and its ``TimelineItemProviderProtocol`` that offers an UI layer oriented interface for dealing
+/// with Room timelines.
+/// It, for example, permits switching from a live timeline to an event focused one, building view specific
+/// timeline items, grouping together state events, donating intents to the larger system etc.
 @MainActor
 protocol TimelineControllerProtocol {
     var roomID: String { get }

ElementX/Sources/Services/Timeline/TimelineItemProviderProtocol.swift

@@ -27,8 +27,10 @@ struct PaginationState: Equatable {
     let forward: PaginationStatus
 }
 
+/// Entities implementing this protocol are responsible for processings diffs coming from the rust timeline
+/// and converting them into an array of Element X specific ``TimelineItemProxy``s that will be
+/// published as an array together with the pagination state through the ``updatePublisher``.
 @MainActor
-// sourcery: AutoMockable
 protocol TimelineItemProviderProtocol {
     /// A publisher that signals when ``itemProxies`` or ``paginationState`` are changed.
     var updatePublisher: AnyPublisher<([TimelineItemProxy], PaginationState), Never> { get }
@@ -43,3 +45,6 @@ protocol TimelineItemProviderProtocol {
     /// This is temporary and will be replace by a subscription on the room itself.
     var membershipChangePublisher: AnyPublisher<Void, Never> { get }
 }
+
+// sourcery: AutoMockable
+extension TimelineItemProviderProtocol { }

ElementX/Sources/Services/Timeline/TimelineProxyProtocol.swift

@@ -37,7 +37,9 @@ enum TimelineProxyError: Error {
     case failedPaginatingEndReached
 }
 
-// sourcery: AutoMockable
+/// Element X proxies generally wrap the counterpart RustSDK objects while providing platform specific
+/// interfaces. In this case it composes methods for interacting with a room's timeline and should be used alongside
+/// the ``TimelineItemProviderProtocol`` which offers a reactive interface to timeline changes.
 protocol TimelineProxyProtocol {
     var timelineItemProvider: TimelineItemProviderProtocol { get }
 
@@ -125,3 +127,6 @@ protocol TimelineProxyProtocol {
                                 html: String?,
                                 intentionalMentions: Mentions) -> RoomMessageEventContentWithoutRelation
 }
+
+// sourcery: AutoMockable
+extension TimelineProxyProtocol { }