Add KDoc to the libraries/session-storage API interfaces

Document SessionStore, SessionObserver and SessionListener at the interface level
and add the missing @param entries.

The store doc records that sessions are ordered by last usage, which is what makes
"the latest session" meaningful across the rest of the interface, and the listener
doc explains that wasLastSession is the signal to clean up app-wide data too.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

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)
 }

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) {}
 }

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)
 }