Apply suggestions from code review

Co-authored-by: Richard van der Hoff <[email protected]>
Signed-off-by: Valere <[email protected]>

crates/matrix-sdk-crypto/src/types/events/utd_cause.rs

@@ -48,12 +48,13 @@ pub enum UtdCause {
     /// obtained from a legacy (asymmetric) backup, unsafe key forward, etc.)
     UnknownDevice = 4,
 
-    /// We are missing the keys for this event, but it is a "device historical"
+    /// We are missing the keys for this event, but it is a "device-historical"
     /// message and no backup is accessible or usable.
-    /// Device historical means that the message was sent before the current
-    /// device existed, but the current user is a member of the room. Not to
-    /// be confounded to pre-join or pre-invite messages (see
-    /// `SentBeforeWeJoined` for that).
+    /// Device-historical means that the message was sent before the current
+    /// device existed (but the current user was probably a member of the room
+    /// at the time the message was sent). Not to
+    /// be confused with pre-join or pre-invite messages (see
+    /// [`SentBeforeWeJoined`] for that).
     HistoricalMessage = 5,
 }
 
@@ -79,8 +80,8 @@ enum Membership {
 #[derive(Debug, Clone, Copy)]
 pub struct CryptoContextInfo {
     /// The current device creation timestamp, used as a heuristic to determine
-    /// if an event is device historical or not (sent before the current device
-    /// existed)
+    /// if an event is device-historical or not (sent before the current device
+    /// existed).
     pub device_creation_ts: MilliSecondsSinceUnixEpoch,
     /// True if key storage is correctly set up and can be used by the current
     /// client to download and decrypt message keys.
@@ -120,7 +121,7 @@ impl UtdCause {
                         && timeline_event.origin_server_ts()
                             < crypto_context_info.device_creation_ts
                     {
-                        // It's a device historical message and there is no accessible
+                        // It's a device-historical message and there is no accessible
                         // backup. The key is missing and it
                         // is expected.
                         return UtdCause::HistoricalMessage;

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

@@ -118,7 +118,7 @@ impl Flow {
 pub(super) struct TimelineEventContext {
     pub(super) sender: OwnedUserId,
     pub(super) sender_profile: Option<Profile>,
-    /// The event `origin_server_ts` field (or creation time for local echo)
+    /// The event's `origin_server_ts` field (or creation time for local echo).
     pub(super) timestamp: MilliSecondsSinceUnixEpoch,
     pub(super) is_own_event: bool,
     pub(super) read_receipts: IndexMap<OwnedUserId, Receipt>,
@@ -178,12 +178,16 @@ pub(super) enum TimelineEventKind {
 }
 
 impl TimelineEventKind {
-    /// Creates a new `TimelineEventKind` with the given event and room version.
+    /// Creates a new `TimelineEventKind`.
+    ///
+    /// # Arguments
+    ///
+    /// * `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`.
     pub async fn from_event<P: RoomDataProvider>(
         event: AnySyncTimelineEvent,
-        // We need also the [`Raw`] version of the `event` because unknown json fields are lost
-        // when de-serialising to the actual `AnySyncTimelineEvent` type. And we need some
-        // of these field to determine the `UtdCause`.
         raw_event: &Raw<AnySyncTimelineEvent>,
         room_data_provider: &P,
         unable_to_decrypt_info: Option<UnableToDecryptInfo>,