docs(spaces): add documentation, comments and examples

Author: stefanceriu

Cargo.lock

@@ -67,6 +67,7 @@ assert-json-diff.workspace = true
 assert_matches.workspace = true
 assert_matches2.workspace = true
 eyeball-im-util.workspace = true
+futures-executor.workspace = true
 matrix-sdk = { workspace = true, features = ["testing", "sqlite"] }
 matrix-sdk-test.workspace = true
 matrix-sdk-test-utils.workspace = true

crates/matrix-sdk-ui/Cargo.toml

@@ -30,6 +30,9 @@ impl SpaceGraphNode {
 }
 
 #[derive(Debug)]
+/// A graph structure representing a space hierarchy. Contains functionality
+/// for mapping parent-child relationships between rooms, removing cycles and
+/// retrieving top-level parents/roots.
 pub struct SpaceGraph {
     nodes: BTreeMap<OwnedRoomId, SpaceGraphNode>,
 }
@@ -45,18 +48,25 @@ impl SpaceGraph {
         Self { nodes: BTreeMap::new() }
     }
 
+    /// Returns the root nodes of the graph, which are nodes without any
+    /// parents.
     pub fn root_nodes(&self) -> Vec<&OwnedRoomId> {
         self.nodes.values().filter(|node| node.parents.is_empty()).map(|node| &node.id).collect()
     }
 
+    /// Returns the children of a given node. If the node does not exist, it
+    /// returns an empty vector.
     pub fn children_of(&self, node_id: &OwnedRoomId) -> Vec<&OwnedRoomId> {
         self.nodes.get(node_id).map_or(vec![], |node| node.children.iter().collect())
     }
 
+    /// Adds a node to the graph. If the node already exists, it does nothing.
     pub fn add_node(&mut self, node_id: OwnedRoomId) {
         self.nodes.entry(node_id.clone()).or_insert(SpaceGraphNode::new(node_id));
     }
 
+    /// Adds a directed edge from `parent_id` to `child_id`, creating nodes if
+    /// they do not already exist in the graph.
     pub fn add_edge(&mut self, parent_id: OwnedRoomId, child_id: OwnedRoomId) {
         self.nodes.entry(parent_id.clone()).or_insert(SpaceGraphNode::new(parent_id.clone()));
 
@@ -66,6 +76,9 @@ impl SpaceGraph {
         self.nodes.get_mut(&child_id).unwrap().parents.insert(parent_id);
     }
 
+    /// Removes cycles in the graph by performing a depth-first search (DFS) and
+    /// remembering the visited nodes. If a node is revisited while still in the
+    /// current path (i.e. it's on the stack), it indicates a cycle.
     pub fn remove_cycles(&mut self) {
         let mut visited = BTreeSet::new();
         let mut stack = BTreeSet::new();

crates/matrix-sdk-ui/src/spaces/graph.rs

@@ -14,7 +14,17 @@
 
 //! High level interfaces for working with Spaces
 //!
-//! See [`SpaceService`] for details.
+//! The `SpaceService` is an UI oriented, high-level interface for working with
+//! Matrix Spaces. It provides methods to retrieve joined spaces, subscribe
+//! to updates, and navigate space hierarchies.
+//!
+//! It consists of 3 main components:
+//! - `SpaceService`: The main service for managing spaces. It
+//! - `SpaceGraph`: An utility that maps the `m.space.parent` and
+//!   `m.space.child` fields into a graph structure, removing cycles and
+//!   providing access to top level parents.
+//! - `SpaceRoomList`: A component for retrieving a space's children rooms and
+//!   their details.
 
 use std::sync::Arc;
 
@@ -39,6 +49,43 @@ pub mod graph;
 pub mod room;
 pub mod room_list;
 
+/// The main entry point into the Spaces facilities.
+///
+/// The spaces service is responsible for retrieving one's joined rooms,
+/// building a graph out of their `m.space.parent` and `m.space.child` state
+/// events, and providing access to the top-level spaces and their children.
+///
+/// # Examples
+///
+/// ```no_run
+/// use futures_util::StreamExt;
+/// use matrix_sdk::Client;
+/// use matrix_sdk_ui::spaces::SpaceService;
+/// use ruma::owned_room_id;
+///
+/// # futures_executor::block_on(async {
+/// let client: Client = todo!();
+/// let space_service = SpaceService::new(client.clone());
+///
+/// // Get a list of all the joined spaces
+/// let joined_spaces = space_service.joined_spaces().await;
+///
+/// // And subscribe to changes on them
+/// // `initial_values` is equal to `joined_spaces` if nothing changed meanwhile
+/// let (initial_values, stream) = space_service.subscribe_to_joined_spaces();
+///
+/// while let Some(diffs) = stream.next().await {
+///     println!("Received joined spaces updates: {diffs:?}");
+/// }
+///
+/// // Get a list of all the rooms in a particular space
+/// let room_list = space_service
+///     .space_room_list(owned_room_id!("!some_space:example.org"));
+///
+/// // Which can be used to retrieve information about the children rooms
+/// let children = room_list.rooms();
+/// # })
+/// ```
 pub struct SpaceService {
     client: Client,
 
@@ -64,6 +111,8 @@ impl SpaceService {
         }
     }
 
+    /// Subscribes to updates on the joined spaces list. If space rooms are
+    /// joined or left, the stream will yield diffs that reflect the changes.
     pub fn subscribe_to_joined_spaces(
         &self,
     ) -> (Vector<SpaceRoom>, VectorSubscriberBatchedStream<SpaceRoom>) {
@@ -96,6 +145,9 @@ impl SpaceService {
         self.joined_spaces.lock().subscribe().into_values_and_batched_stream()
     }
 
+    /// Returns a list of all the top-level joined spaces. It will eagerly
+    /// compute the latest version and also notify subscribers if there were
+    /// any changes.
     pub async fn joined_spaces(&self) -> Vec<SpaceRoom> {
         let spaces = Self::joined_spaces_for(&self.client).await;
 
@@ -104,6 +156,7 @@ impl SpaceService {
         spaces
     }
 
+    /// Returns a `SpaceRoomList` for the given space ID.
     pub fn space_room_list(&self, space_id: OwnedRoomId) -> SpaceRoomList {
         SpaceRoomList::new(self.client.clone(), space_id)
     }
@@ -127,8 +180,11 @@ impl SpaceService {
             .filter_map(|room| room.is_space().then_some(room))
             .collect::<Vec<_>>();
 
+        // Build a graph to hold the parent-child relations
         let mut graph = SpaceGraph::new();
 
+        // Iterate over all joined spaces and populate the graph with edges based
+        // on `m.space.parent` and `m.space.child` state events.
         for space in joined_spaces.iter() {
             graph.add_node(space.room_id().to_owned());
 
@@ -167,6 +223,8 @@ impl SpaceService {
             }
         }
 
+        // Remove cycles from the graph. This is important because they are not
+        // enforced backend side.
         graph.remove_cycles();
 
         let root_notes = graph.root_nodes();

crates/matrix-sdk-ui/src/spaces/mod.rs

@@ -19,6 +19,8 @@ use ruma::{
     room::{JoinRuleSummary, RoomSummary, RoomType},
 };
 
+/// Structure representing a room in a space and aggregated information
+/// relevant to the UI layer.
 #[derive(Debug, Clone, PartialEq)]
 pub struct SpaceRoom {
     pub room_id: OwnedRoomId,

crates/matrix-sdk-ui/src/spaces/room.rs

@@ -33,6 +33,65 @@ pub enum SpaceRoomListPaginationState {
     Loading,
 }
 
+/// The `SpaceRoomList`represents a paginated list of direct rooms
+/// that belong to a particular space.
+///
+/// It can be used to paginate through the list (and have live updates on the
+/// pagination state) as well as subscribe to changes as rooms are joined or
+/// left.
+///
+/// # Examples
+///
+/// ```no_run
+/// use futures_util::StreamExt;
+/// use matrix_sdk::Client;
+/// use matrix_sdk_ui::spaces::{
+///     SpaceService, room_list::SpaceRoomListPaginationState,
+/// };
+/// use ruma::owned_room_id;
+///
+/// # futures_executor::block_on(async {
+/// let client: Client = todo!();
+/// let space_service = SpaceService::new(client.clone());
+///
+/// // Get a list of all the rooms in a particular space
+/// let room_list = space_service
+///     .space_room_list(owned_room_id!("!some_space:example.org"));
+///
+/// // Start off with an empty and idle list
+/// room_list.rooms().is_empty();
+///
+/// assert_eq!(
+///     room_list.pagination_state(),
+///     SpaceRoomListPaginationState::Idle { end_reached: false }
+/// );
+///
+/// // Subscribe to pagination state updates
+/// let pagination_state_stream =
+///     room_list.subscribe_to_pagination_state_updates();
+///
+/// // And to room list updates
+/// let (_, room_stream) = room_list.subscribe_to_room_updates();
+///
+/// // spawn {
+/// while let Some(pagination_state) = pagination_state_stream.next().await {
+///     println!("Received pagination state update: {pagination_state:?}");
+/// };
+/// // }
+///
+/// // spawn {
+/// while let Some(diffs) = room_stream.next().await {
+///     println!("Received room list update: {diffs:?}");
+/// };
+/// // }
+///
+/// // Ask the room to load the next page
+/// room_list.paginate().await.unwrap();
+///
+/// // And, if successful, rooms are available
+/// let rooms = room_list.rooms();
+/// # })
+/// ```
 pub struct SpaceRoomList {
     client: Client,
 
@@ -53,6 +112,7 @@ impl Drop for SpaceRoomList {
     }
 }
 impl SpaceRoomList {
+    /// Creates a new `SpaceRoomList` for the given space identifier.
     pub fn new(client: Client, parent_space_id: OwnedRoomId) -> Self {
         let rooms = Arc::new(Mutex::new(ObservableVector::<SpaceRoom>::new()));
 
@@ -105,26 +165,32 @@ impl SpaceRoomList {
         }
     }
 
+    /// Returns the room list is currently paginating or not.
     pub fn pagination_state(&self) -> SpaceRoomListPaginationState {
         self.pagination_state.get()
     }
 
+    /// Subscribe to pagination updates.
     pub fn subscribe_to_pagination_state_updates(
         &self,
     ) -> Subscriber<SpaceRoomListPaginationState> {
         self.pagination_state.subscribe()
     }
 
+    /// Return the current list of rooms.
     pub fn rooms(&self) -> Vec<SpaceRoom> {
         self.rooms.lock().iter().cloned().collect_vec()
     }
 
+    /// Subscribes to room list updates.
     pub fn subscribe_to_room_updates(
         &self,
     ) -> (Vector<SpaceRoom>, VectorSubscriberBatchedStream<SpaceRoom>) {
         self.rooms.lock().subscribe().into_values_and_batched_stream()
     }
 
+    /// As the list to retrieve the next page if the end hasn't been reached
+    /// yet. Otherwise it no-ops.
     pub async fn paginate(&self) -> Result<(), Error> {
         match *self.pagination_state.read() {
             SpaceRoomListPaginationState::Idle { end_reached } if end_reached => {