From b66c666997cbcf32071d24ffe2484a215de8d0e4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Damir=20Jeli=C4=87?= <poljar@termina.org.uk>
Date: Thu, 28 Jan 2021 14:59:57 +0100
Subject: [PATCH] base: Expose and document the stripped room info

---
 matrix_sdk_base/src/lib.rs            |  5 ++++-
 matrix_sdk_base/src/rooms/stripped.rs | 32 ++++++++++++++++++++++-----
 2 files changed, 30 insertions(+), 7 deletions(-)

diff --git a/matrix_sdk_base/src/lib.rs b/matrix_sdk_base/src/lib.rs
index 8566c12c..15731b1a 100644
--- a/matrix_sdk_base/src/lib.rs
+++ b/matrix_sdk_base/src/lib.rs
@@ -52,7 +52,10 @@ mod session;
 mod store;
 
 pub use event_emitter::EventEmitter;
-pub use rooms::{InvitedRoom, JoinedRoom, LeftRoom, Room, RoomInfo, RoomMember, RoomState};
+pub use rooms::{
+    InvitedRoom, JoinedRoom, LeftRoom, Room, RoomInfo, RoomMember, RoomState, StrippedRoom,
+    StrippedRoomInfo,
+};
 pub use store::{StateStore, Store, StoreError};
 
 pub use client::{BaseClient, BaseClientConfig, RoomStateType};
diff --git a/matrix_sdk_base/src/rooms/stripped.rs b/matrix_sdk_base/src/rooms/stripped.rs
index 5dd0dceb..447e4886 100644
--- a/matrix_sdk_base/src/rooms/stripped.rs
+++ b/matrix_sdk_base/src/rooms/stripped.rs
@@ -24,6 +24,7 @@ use crate::store::StateStore;
 
 use super::BaseRoomInfo;
 
+/// The underlying room data structure collecting state for invited rooms.
 #[derive(Debug, Clone)]
 pub struct StrippedRoom {
     room_id: Arc<RoomId>,
@@ -33,7 +34,11 @@ pub struct StrippedRoom {
 }
 
 impl StrippedRoom {
-    pub fn new(own_user_id: &UserId, store: Arc<Box<dyn StateStore>>, room_id: &RoomId) -> Self {
+    pub(crate) fn new(
+        own_user_id: &UserId,
+        store: Arc<Box<dyn StateStore>>,
+        room_id: &RoomId,
+    ) -> Self {
         let room_id = Arc::new(room_id.clone());
 
         let info = StrippedRoomInfo {
@@ -44,7 +49,7 @@ impl StrippedRoom {
         Self::restore(own_user_id, store, info)
     }
 
-    pub fn restore(
+    pub(crate) fn restore(
         own_user_id: &UserId,
         store: Arc<Box<dyn StateStore>>,
         room_info: StrippedRoomInfo,
@@ -72,6 +77,12 @@ impl StrippedRoom {
         }
     }
 
+    /// Get the unique room id of the room.
+    pub fn room_id(&self) -> &RoomId {
+        &self.room_id
+    }
+
+    /// Get our own user id.
     pub fn own_user_id(&self) -> &UserId {
         &self.own_user_id
     }
@@ -80,22 +91,31 @@ impl StrippedRoom {
         (*self.inner.lock().unwrap()).clone()
     }
 
+    /// Is the room encrypted.
     pub fn is_encrypted(&self) -> bool {
         self.inner.lock().unwrap().base_info.encryption.is_some()
     }
 
-    pub fn room_id(&self) -> &RoomId {
-        &self.room_id
-    }
-
+    /// Calculate the canonical display name of the room, taking into account
+    /// its name, aliases and members.
+    ///
+    /// The display name is calculated according to [this algorithm][spec].
+    ///
+    /// [spec]: <https://matrix.org/docs/spec/client_server/latest#calculating-the-display-name-for-a-room>
     pub async fn display_name(&self) -> String {
         self.calculate_name().await
     }
 }
 
+/// The underlying pure data structure for invited rooms.
+///
+/// Holds all the info needed to persist a room into the state store.
 #[derive(Clone, Debug, Serialize, Deserialize)]
 pub struct StrippedRoomInfo {
+    /// The unique room id of the room.
     pub room_id: Arc<RoomId>,
+    /// Base room info which holds some basic event contents important for the
+    /// room state.
     pub base_info: BaseRoomInfo,
 }