From 6b56c9efd83deb1121bb2f1f9eec0a73d6073a07 Mon Sep 17 00:00:00 2001
From: Ivan Enderlin <ivan@mnt.io>
Date: Mon, 9 Dec 2024 16:39:40 +0100
Subject: [PATCH] doc(ui): Explain why `Deref` is fine, but `DerefMut` is not.

---
 .../timeline/controller/observable_items.rs    | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/crates/matrix-sdk-ui/src/timeline/controller/observable_items.rs b/crates/matrix-sdk-ui/src/timeline/controller/observable_items.rs
index a1b6697ae..ad2af19c0 100644
--- a/crates/matrix-sdk-ui/src/timeline/controller/observable_items.rs
+++ b/crates/matrix-sdk-ui/src/timeline/controller/observable_items.rs
@@ -124,6 +124,10 @@ impl ObservableItems {
 }
 
 // It's fine to deref to an immutable reference to `Vector`.
+//
+// We don't want, however, to deref to a mutable reference: it should be done
+// via proper methods to control precisely the mapping between remote events and
+// timeline items.
 impl Deref for ObservableItems {
     type Target = Vector<Arc<TimelineItem>>;
 
@@ -154,6 +158,11 @@ impl ObservableItemsEntry<'_> {
     }
 }
 
+// It's fine to deref to an immutable reference to `Arc<TimelineItem>`.
+//
+// We don't want, however, to deref to a mutable reference: it should be done
+// via proper methods to control precisely the mapping between remote events and
+// timeline items.
 impl Deref for ObservableItemsEntry<'_> {
     type Target = Arc<TimelineItem>;
 
@@ -302,6 +311,10 @@ impl<'observable_items> ObservableItemsTransaction<'observable_items> {
 }
 
 // It's fine to deref to an immutable reference to `Vector`.
+//
+// We don't want, however, to deref to a mutable reference: it should be done
+// via proper methods to control precisely the mapping between remote events and
+// timeline items.
 impl Deref for ObservableItemsTransaction<'_> {
     type Target = Vector<Arc<TimelineItem>>;
 
@@ -335,6 +348,11 @@ impl ObservableItemsTransactionEntry<'_, '_> {
     }
 }
 
+// It's fine to deref to an immutable reference to `Arc<TimelineItem>`.
+//
+// We don't want, however, to deref to a mutable reference: it should be done
+// via proper methods to control precisely the mapping between remote events and
+// timeline items.
 impl Deref for ObservableItemsTransactionEntry<'_, '_> {
     type Target = Arc<TimelineItem>;