From 590f99a5c247ec1df2afdde5f378c269b3d6d17a Mon Sep 17 00:00:00 2001
From: ericdecanini <eddecanini@gmail.com>
Date: Thu, 28 Jul 2022 11:33:54 +0200
Subject: [PATCH] Adds comments to SpaceStateHandler

---
 .../java/im/vector/app/SpaceStateHandler.kt   | 28 +++++++++++++++++++
 1 file changed, 28 insertions(+)

diff --git a/vector/src/main/java/im/vector/app/SpaceStateHandler.kt b/vector/src/main/java/im/vector/app/SpaceStateHandler.kt
index 7a98025734..174b8ab3cd 100644
--- a/vector/src/main/java/im/vector/app/SpaceStateHandler.kt
+++ b/vector/src/main/java/im/vector/app/SpaceStateHandler.kt
@@ -22,10 +22,27 @@ import kotlinx.coroutines.flow.Flow
 import org.matrix.android.sdk.api.session.Session
 import org.matrix.android.sdk.api.session.room.model.RoomSummary
 
+/**
+ * Gets info about the current space the user has navigated to, any space backstack they may have
+ * and handles switching to different spaces
+ */
 interface SpaceStateHandler : DefaultLifecycleObserver {
 
+    /**
+     * Gets the current space the current user has navigated to
+     *
+     * @return null if the user is not in
+     */
     fun getCurrentSpace(): RoomSummary?
 
+    /**
+     * Sets the new space the current user is navigating to
+     *
+     * @param spaceId the id of the space being navigated to
+     * @param session the current active session
+     * @param persistNow if true, the current space will immediately be persisted in shared prefs
+     * @param isForwardNavigation whether this navigation is a forward action to properly handle backstack
+     */
     fun setCurrentSpace(
             spaceId: String?,
             session: Session? = null,
@@ -33,9 +50,20 @@ interface SpaceStateHandler : DefaultLifecycleObserver {
             isForwardNavigation: Boolean = true,
     )
 
+    /**
+     * Gets the current backstack of spaces (via their id)
+     *
+     * null may be an entry in the ArrayDeque to indicate the root space (All Chats)
+     */
     fun getSpaceBackstack(): ArrayDeque<String?>
 
+    /**
+     * Gets a flow of the selected space for clients to react immediately to space changes
+     */
     fun getSelectedSpaceFlow(): Flow<Option<RoomSummary>>
 
+    /**
+     * Gets the id of the active space, or null if there is none
+     */
     fun getSafeActiveSpaceId(): String?
 }