refactor(timeline): rename TimelineEventKind into TimelineAction and add comments

Author: bnjbvr

crates/matrix-sdk-ui/src/timeline/controller/state.rs

@@ -34,8 +34,7 @@ use super::{
     super::{
         date_dividers::DateDividerAdjuster,
         event_handler::{
-            Flow, TimelineEventContext, TimelineEventHandler, TimelineEventKind,
-            TimelineItemPosition,
+            Flow, TimelineAction, TimelineEventContext, TimelineEventHandler, TimelineItemPosition,
         },
         event_item::RemoteEventOrigin,
         traits::RoomDataProvider,
@@ -164,11 +163,11 @@ impl TimelineState {
 
         let mut date_divider_adjuster = DateDividerAdjuster::new(date_divider_mode);
 
-        if let Some(timeline_event_kind) =
-            TimelineEventKind::from_content(content, None, None, None, &txn.items, &mut txn.meta)
+        if let Some(timeline_action) =
+            TimelineAction::from_content(content, None, None, None, &txn.items, &mut txn.meta)
         {
             TimelineEventHandler::new(&mut txn, ctx)
-                .handle_event(&mut date_divider_adjuster, timeline_event_kind)
+                .handle_event(&mut date_divider_adjuster, timeline_action)
                 .await;
             txn.adjust_date_dividers(date_divider_adjuster);
         }

crates/matrix-sdk-ui/src/timeline/controller/state_transaction.rs

@@ -25,7 +25,7 @@ use super::{
         controller::{FullEventMeta, ObservableItemsTransactionEntry},
         date_dividers::DateDividerAdjuster,
         event_handler::{
-            Flow, HandleEventResult, TimelineEventContext, TimelineEventHandler, TimelineEventKind,
+            Flow, HandleEventResult, TimelineEventContext, TimelineEventHandler,
             TimelineItemPosition,
         },
         event_item::RemoteEventOrigin,
@@ -34,7 +34,10 @@ use super::{
     ObservableItems, ObservableItemsTransaction, TimelineFocusKind, TimelineMetadata,
     TimelineSettings,
 };
-use crate::{events::SyncTimelineEventWithoutContent, timeline::VirtualTimelineItem};
+use crate::{
+    events::SyncTimelineEventWithoutContent,
+    timeline::{event_handler::TimelineAction, VirtualTimelineItem},
+};
 
 pub(in crate::timeline) struct TimelineStateTransaction<'a> {
     /// A vector transaction over the items themselves. Holds temporary state
@@ -248,7 +251,8 @@ impl<'a> TimelineStateTransaction<'a> {
             _ => (kind.into_raw(), None),
         };
 
-        let (event_id, sender, timestamp, txn_id, event_kind, should_add) = match raw.deserialize()
+        let (event_id, sender, timestamp, txn_id, timeline_action, should_add) = match raw
+            .deserialize()
         {
             // Classical path: the event is valid, can be deserialized, everything is alright.
             Ok(event) => {
@@ -312,7 +316,7 @@ impl<'a> TimelineStateTransaction<'a> {
                     event.sender().to_owned(),
                     event.origin_server_ts(),
                     event.transaction_id().map(ToOwned::to_owned),
-                    TimelineEventKind::from_event(
+                    TimelineAction::from_event(
                         event,
                         &raw,
                         room_data_provider,
@@ -334,7 +338,7 @@ impl<'a> TimelineStateTransaction<'a> {
                     event.sender().to_owned(),
                     event.origin_server_ts(),
                     event.transaction_id().map(ToOwned::to_owned),
-                    Some(TimelineEventKind::failed_to_parse(event, e)),
+                    Some(TimelineAction::failed_to_parse(event, e)),
                     true,
                 ),
 
@@ -443,9 +447,9 @@ impl<'a> TimelineStateTransaction<'a> {
         };
 
         // Handle the event to create or update a timeline item.
-        if let Some(event_kind) = event_kind {
+        if let Some(timeline_action) = timeline_action {
             TimelineEventHandler::new(self, ctx)
-                .handle_event(date_divider_adjuster, event_kind)
+                .handle_event(date_divider_adjuster, timeline_action)
                 .await
         } else {
             HandleEventResult::default()

crates/matrix-sdk-ui/src/timeline/event_handler.rs

@@ -138,30 +138,44 @@ pub(super) enum HandleAggregationKind {
     PollEnd,
 }
 
+/// An action that we want to cause on the timeline.
 #[derive(Clone, Debug)]
-pub(super) enum TimelineEventKind {
-    AddItem { content: TimelineItemContent, edit_json: Option<Raw<AnySyncTimelineEvent>> },
+pub(super) enum TimelineAction {
+    /// Add a new timeline item.
+    ///
+    /// This enqueues adding a new item to the timeline (i.e. push to the items
+    /// array in its state). The item may be filtered out, and thus not
+    /// added later.
+    AddItem {
+        /// The content of the item we want to add.
+        content: TimelineItemContent,
+        /// The latest edit JSON for this item.
+        edit_json: Option<Raw<AnySyncTimelineEvent>>,
+    },
 
-    HandleAggregation { related_event: OwnedEventId, kind: HandleAggregationKind },
+    /// Handle an aggregation to another event.
+    ///
+    /// The event the aggregation is related to might not be included in the
+    /// timeline, in which case it will be stashed somewhere, until we see
+    /// the related event.
+    HandleAggregation {
+        /// To which other event does this aggregation apply to?
+        related_event: OwnedEventId,
+        /// What kind of aggregation are we handling here?
+        kind: HandleAggregationKind,
+    },
 }
 
-impl TimelineEventKind {
+impl TimelineAction {
     /// Create a new [`TimelineEventKind::AddItem`] with no edit json.
     fn add_item(content: TimelineItemContent) -> Self {
         Self::AddItem { content, edit_json: None }
     }
 
-    /// Creates a new `TimelineEventKind`.
-    ///
-    /// # Arguments
+    /// Create a new [`TimelineAction`] from a given remote event.
     ///
-    /// * `event` - The event for which we should create a `TimelineEventKind`.
-    /// * `raw_event` - The [`Raw`] JSON for `event`. (Required so that we can
-    ///   access `unsigned` data.)
-    /// * `room_data_provider` - An object which will provide information about
-    ///   the room containing the event.
-    /// * `unable_to_decrypt_info` - If `event` represents a failure to decrypt,
-    ///   information about that failure. Otherwise, `None`.
+    /// The return value may be `None` if handling the event (be it a new item
+    /// or an aggregation) is not supported for this event type.
     pub async fn from_event<P: RoomDataProvider>(
         event: AnySyncTimelineEvent,
         raw_event: &Raw<AnySyncTimelineEvent>,
@@ -274,6 +288,14 @@ impl TimelineEventKind {
         })
     }
 
+    /// Create a new [`TimelineAction`] from a given event's content.
+    ///
+    /// This is applicable to both remote event (as this is called from
+    /// [`TimelineAction::from_event`]) or local events (for which we only have
+    /// the content).
+    ///
+    /// The return value may be `None` if handling the event (be it a new item
+    /// or an aggregation) is not supported for this event type.
     pub(super) fn from_content(
         content: AnyMessageLikeEventContent,
         raw_event: Option<&Raw<AnySyncTimelineEvent>>,
@@ -588,7 +610,7 @@ impl<'a, 'o> TimelineEventHandler<'a, 'o> {
     pub(super) async fn handle_event(
         mut self,
         date_divider_adjuster: &mut DateDividerAdjuster,
-        event_kind: TimelineEventKind,
+        timeline_action: TimelineAction,
     ) -> HandleEventResult {
         let span = tracing::Span::current();
 
@@ -610,14 +632,14 @@ impl<'a, 'o> TimelineEventHandler<'a, 'o> {
             }
         };
 
-        match event_kind {
-            TimelineEventKind::AddItem { content, edit_json } => {
+        match timeline_action {
+            TimelineAction::AddItem { content, edit_json } => {
                 if self.ctx.should_add_new_items {
                     self.add_item(content, edit_json);
                 }
             }
 
-            TimelineEventKind::HandleAggregation { related_event, kind } => match kind {
+            TimelineAction::HandleAggregation { related_event, kind } => match kind {
                 HandleAggregationKind::Reaction { key } => {
                     self.handle_reaction(related_event, key);
                 }