Add KDoc to the services/appnavstate API interfaces

Document the members of AppNavigationStateService and AppForegroundStateService
that had none, and add the missing @param entries.

The recurring `owner` parameter is now explained, from
DefaultAppNavigationStateService: the navigation state is a stack, pushing a level
without its parent logs an error and does nothing, and a leave call whose owner
does not match the current level is silently ignored so that a node which has
already been replaced cannot pop someone else's state.

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

services/appnavstate/api/src/main/kotlin/io/element/android/services/appnavstate/api/AppForegroundStateService.kt

@@ -34,27 +34,41 @@ interface AppForegroundStateService {
      */
     val isSyncingNotificationEvent: StateFlow<Boolean>
 
+    /**
+     * Updates to whether the app is publishing a live location will be emitted here.
+     */
     val isSharingLiveLocation: StateFlow<Boolean>
 
     /**
-     * Start observing the foreground state.
+     * Start observing the foreground state; to be called once when the app process starts.
      */
     fun startObservingForeground()
 
     /**
      * Update the in-call state.
+     *
+     * @param isInCall true while the user is in a call, which keeps the session syncing even in the background.
      */
     fun updateIsInCallState(isInCall: Boolean)
 
     /**
      * Update the 'has ringing call' state.
+     *
+     * @param hasRingingCall true while an incoming call is ringing and has not yet been answered or declined.
      */
     fun updateHasRingingCall(hasRingingCall: Boolean)
 
     /**
      * Update the active state for the syncing notification event flow.
+     *
+     * @param isSyncingNotificationEvent true while a push is being resolved, so the sync is not stopped mid-way.
      */
     fun updateIsSyncingNotificationEvent(isSyncingNotificationEvent: Boolean)
 
+    /**
+     * Update the live location sharing state.
+     *
+     * @param isSharingLiveLocation true while at least one live location share is active on this device.
+     */
     fun updateIsSharingLiveLocation(isSharingLiveLocation: Boolean)
 }

services/appnavstate/api/src/main/kotlin/io/element/android/services/appnavstate/api/AppNavigationStateService.kt

@@ -17,14 +17,55 @@ import kotlinx.coroutines.flow.StateFlow
  * A service that tracks the navigation and foreground states of the app.
  */
 interface AppNavigationStateService {
+    /**
+     * Where the user currently is, as a stack that deepens from root to session, room and thread.
+     * Used by the components that need to know what is on screen, notably to suppress the notifications of the room being read.
+     */
     val appNavigationState: StateFlow<AppNavigationState>
 
+    /**
+     * Pushes a session onto the navigation state.
+     *
+     * @param owner identifies the navigation node reporting this, so that a later leave call can be matched to it.
+     * @param sessionId the session that was opened.
+     */
     fun onNavigateToSession(owner: String, sessionId: SessionId)
+
+    /**
+     * Pops back to the root. Does nothing when [owner] is not the owner of the current state, which is how out-of-order
+     * calls from a node that has already been replaced are ignored.
+     *
+     * @param owner the same value passed to [onNavigateToSession].
+     */
     fun onLeavingSession(owner: String)
 
+    /**
+     * Pushes a room onto the navigation state. Logs an error and does nothing unless a session was pushed first.
+     *
+     * @param owner identifies the navigation node reporting this.
+     * @param roomId the room that was opened.
+     */
     fun onNavigateToRoom(owner: String, roomId: RoomId)
+
+    /**
+     * Pops back to the parent session; as with [onLeavingSession], a mismatched [owner] makes this a no-op.
+     *
+     * @param owner the same value passed to [onNavigateToRoom].
+     */
     fun onLeavingRoom(owner: String)
 
+    /**
+     * Pushes a thread onto the navigation state. Logs an error and does nothing unless a room was pushed first.
+     *
+     * @param owner identifies the navigation node reporting this.
+     * @param threadId the thread that was opened.
+     */
     fun onNavigateToThread(owner: String, threadId: ThreadId)
+
+    /**
+     * Pops back to the parent room; as with [onLeavingSession], a mismatched [owner] makes this a no-op.
+     *
+     * @param owner the same value passed to [onNavigateToThread].
+     */
     fun onLeavingThread(owner: String)
 }