diff --git a/libraries/session-storage/api/src/main/kotlin/io/element/android/libraries/sessionstorage/api/SessionStore.kt b/libraries/session-storage/api/src/main/kotlin/io/element/android/libraries/sessionstorage/api/SessionStore.kt
index fb60311418..53aa0c9516 100644
--- a/libraries/session-storage/api/src/main/kotlin/io/element/android/libraries/sessionstorage/api/SessionStore.kt
+++ b/libraries/session-storage/api/src/main/kotlin/io/element/android/libraries/sessionstorage/api/SessionStore.kt
@@ -11,6 +11,11 @@ package io.element.android.libraries.sessionstorage.api
 import kotlinx.coroutines.flow.Flow
 import kotlinx.coroutines.flow.map
 
+/**
+ * Persists the logged in sessions and their access tokens, so the app can restore them after a restart.
+ *
+ * Sessions are ordered by last usage, which is what makes "the latest session" meaningful across the interface.
+ */
 interface SessionStore {
     /**
      * A flow emitting the current logged in state.
@@ -28,21 +33,32 @@ interface SessionStore {
      * Add a new session. If other sessions exist, the new one will be set as the latest used one, and
      * the added session position will be set to a value higher than the other session positions.
      */
+    /**
+     * @param sessionData the session to store, including its tokens.
+     */
     suspend fun addSession(sessionData: SessionData)
 
     /**
      * Will update the session data matching the userId, except the value of loginTimestamp.
      * No op if userId is not found in DB.
+     *
+     * @param sessionData the new content of the session.
      */
     suspend fun updateData(sessionData: SessionData)
 
     /**
      * Update the user profile info of the session matching the userId.
+     *
+     * @param sessionId the session to update.
+     * @param displayName the new display name, or `null` when the user has none.
+     * @param avatarUrl the new avatar, or `null` when the user has none.
      */
     suspend fun updateUserProfile(sessionId: String, displayName: String?, avatarUrl: String?)
 
     /**
      * Get the session data matching the userId, or null if not found.
+     *
+     * @param sessionId the session to read.
      */
     suspend fun getSession(sessionId: String): SessionData?
 
@@ -63,11 +79,15 @@ interface SessionStore {
 
     /**
      * Set the session with [sessionId] as the latest used one.
+     *
+     * @param sessionId the session to bring to the front of the ordering.
      */
     suspend fun setLatestSession(sessionId: String)
 
     /**
      * Remove the session matching the sessionId.
+     *
+     * @param sessionId the session to forget, which also discards its tokens.
      */
     suspend fun removeSession(sessionId: String)
 }
diff --git a/libraries/session-storage/api/src/main/kotlin/io/element/android/libraries/sessionstorage/api/observer/SessionListener.kt b/libraries/session-storage/api/src/main/kotlin/io/element/android/libraries/sessionstorage/api/observer/SessionListener.kt
index 8dadcafc7d..8d94af5b13 100644
--- a/libraries/session-storage/api/src/main/kotlin/io/element/android/libraries/sessionstorage/api/observer/SessionListener.kt
+++ b/libraries/session-storage/api/src/main/kotlin/io/element/android/libraries/sessionstorage/api/observer/SessionListener.kt
@@ -8,7 +8,22 @@
 
 package io.element.android.libraries.sessionstorage.api.observer
 
+/**
+ * Reacts to sessions being created or deleted; both methods have an empty default so a listener only overrides what it cares about.
+ */
 interface SessionListener {
+    /**
+     * Called after a session has been stored, for instance following a login.
+     *
+     * @param userId the session that was created.
+     */
     suspend fun onSessionCreated(userId: String) {}
+
+    /**
+     * Called after a session has been removed, which is where per-session data should be cleaned up.
+     *
+     * @param userId the session that was deleted.
+     * @param wasLastSession true when no session remains, so app-wide data can be cleaned up too.
+     */
     suspend fun onSessionDeleted(userId: String, wasLastSession: Boolean) {}
 }
diff --git a/libraries/session-storage/api/src/main/kotlin/io/element/android/libraries/sessionstorage/api/observer/SessionObserver.kt b/libraries/session-storage/api/src/main/kotlin/io/element/android/libraries/sessionstorage/api/observer/SessionObserver.kt
index fb120acd56..08925ee688 100644
--- a/libraries/session-storage/api/src/main/kotlin/io/element/android/libraries/sessionstorage/api/observer/SessionObserver.kt
+++ b/libraries/session-storage/api/src/main/kotlin/io/element/android/libraries/sessionstorage/api/observer/SessionObserver.kt
@@ -8,7 +8,17 @@
 
 package io.element.android.libraries.sessionstorage.api.observer
 
+/**
+ * Notifies interested components when a session is created or deleted, so they can set up or clean up their own per-session data.
+ */
 interface SessionObserver {
+    /**
+     * @param listener the listener to notify from now on.
+     */
     fun addListener(listener: SessionListener)
+
+    /**
+     * @param listener the listener to stop notifying.
+     */
     fun removeListener(listener: SessionListener)
 }