doc(sdk): Add missing documentation.

Author: Hywan

crates/matrix-sdk/src/event_cache/room/mod.rs

@@ -812,6 +812,15 @@ mod private {
             })
         }
 
+        /// Lock this [`RoomEventCacheStateLock`] with per-thread shared access.
+        ///
+        /// This method locks the per-thread lock over the state, and then locks
+        /// the cross-process lock over the store. It returns an RAII guard
+        /// which will drop the read access to the state and to the store when
+        /// dropped.
+        ///
+        /// If the cross-process lock over the store is dirty (see
+        /// [`EventCacheStoreLockState`]), the state is reset to the last chunk.
         pub async fn read(&self) -> Result<RoomEventCacheStateLockReadGuard<'_>, EventCacheError> {
             // Take a write-lock in case the lock is dirty and we need to reset the state.
             let state_guard = self.locked_state.write().await;
@@ -843,6 +852,16 @@ mod private {
             }
         }
 
+        /// Lock this [`RoomEventCacheStateLock`] with exclusive per-thread
+        /// write access.
+        ///
+        /// This method locks the per-thread lock over the state, and then locks
+        /// the cross-process lock over the store. It returns an RAII guard
+        /// which will drop the write access to the state and to the store when
+        /// dropped.
+        ///
+        /// If the cross-process lock over the store is dirty (see
+        /// [`EventCacheStoreLockState`]), the state is reset to the last chunk.
         pub async fn write(
             &self,
         ) -> Result<RoomEventCacheStateLockWriteGuard<'_>, EventCacheError> {
@@ -868,13 +887,23 @@ mod private {
         }
     }
 
+    /// The read lock guard returned by [`RoomEventCacheStateLock::read`].
     pub struct RoomEventCacheStateLockReadGuard<'a> {
+        /// The per-thread read lock guard over the
+        /// [`RoomEventCacheStateLockInner`].
         state: RwLockReadGuard<'a, RoomEventCacheStateLockInner>,
+
+        /// The cross-process lock guard over the store.
         store: EventCacheStoreLockGuard,
     }
 
+    /// The write lock guard return by [`RoomEventCacheStateLock::write`].
     pub struct RoomEventCacheStateLockWriteGuard<'a> {
+        /// The per-thread write lock guard over the
+        /// [`RoomEventCacheStateLockInner`].
         state: RwLockWriteGuard<'a, RoomEventCacheStateLockInner>,
+
+        /// The cross-process lock guard over the store.
         store: EventCacheStoreLockGuard,
     }