From d0a1011638e08c7b1138bc99d7e9ecf7c21bf25b Mon Sep 17 00:00:00 2001
From: Benoit Marty <benoit@matrix.org>
Date: Fri, 14 Aug 2026 15:48:35 +0200
Subject: [PATCH] Add documentation on LinkNewDesktopHandler and
 LinkNewMobileHandler

---
 .../impl/LinkNewDesktopHandler.kt             | 21 ++++++++++++++++++
 .../impl/LinkNewMobileHandler.kt              | 22 +++++++++++++++++++
 2 files changed, 43 insertions(+)

diff --git a/features/linknewdevice/impl/src/main/kotlin/io/element/android/features/linknewdevice/impl/LinkNewDesktopHandler.kt b/features/linknewdevice/impl/src/main/kotlin/io/element/android/features/linknewdevice/impl/LinkNewDesktopHandler.kt
index 6f5beafbd9..bff81a3e9e 100644
--- a/features/linknewdevice/impl/src/main/kotlin/io/element/android/features/linknewdevice/impl/LinkNewDesktopHandler.kt
+++ b/features/linknewdevice/impl/src/main/kotlin/io/element/android/features/linknewdevice/impl/LinkNewDesktopHandler.kt
@@ -39,6 +39,10 @@ class LinkNewDesktopHandler(
         LinkDesktopStep.Uninitialized
     )
 
+    /**
+     * A [StateFlow] that emits the current step of the link desktop process.
+     * It starts with [LinkDesktopStep.Uninitialized] and will emit other steps as they occur.
+     */
     val stepFlow: StateFlow<LinkDesktopStep>
         get() = linkDesktopStepFlow.asStateFlow()
 
@@ -53,6 +57,9 @@ class LinkNewDesktopHandler(
         timerJob = null
     }
 
+    /**
+     * Starts (or restarts) a timer that will emit an error in [stepFlow] after 2 minutes.
+     */
     fun startTimer() {
         timerJob?.cancel()
         timerJob = sessionScope.launch {
@@ -61,12 +68,20 @@ class LinkNewDesktopHandler(
         }
     }
 
+    /**
+     * Creates a new [LinkDesktopHandler] and cancels any existing job.
+     * This should be called when the user wants to retry scanning a QR code.
+     */
     fun createNewHandler() {
         currentJob?.cancel()
         currentJob = null
         handler = matrixClient.createLinkDesktopHandler().getOrNull()
     }
 
+    /**
+     * Resets the state of the handler and cancels any existing job.
+     * This should be called when the user wants to start over.
+     */
     fun reset() {
         resetJobs()
         sessionScope.launch {
@@ -74,6 +89,12 @@ class LinkNewDesktopHandler(
         }
     }
 
+    /**
+     * Handles the scanned QR code data.
+     * This should be called when the user scans a QR code.
+     *
+     * @param data The scanned QR code data as a byte array.
+     */
     fun onScannedCode(data: ByteArray) {
         resetJobs()
         val currentHandler = handler
diff --git a/features/linknewdevice/impl/src/main/kotlin/io/element/android/features/linknewdevice/impl/LinkNewMobileHandler.kt b/features/linknewdevice/impl/src/main/kotlin/io/element/android/features/linknewdevice/impl/LinkNewMobileHandler.kt
index 39c9c6fef3..9436c0e901 100644
--- a/features/linknewdevice/impl/src/main/kotlin/io/element/android/features/linknewdevice/impl/LinkNewMobileHandler.kt
+++ b/features/linknewdevice/impl/src/main/kotlin/io/element/android/features/linknewdevice/impl/LinkNewMobileHandler.kt
@@ -40,9 +40,19 @@ class LinkNewMobileHandler(
         LinkMobileStep.Uninitialized
     )
 
+    /**
+     * A [StateFlow] that emits the current step of the link mobile process.
+     * It starts with [LinkMobileStep.Uninitialized] and will emit other steps as they occur.
+     */
     val stepFlow: StateFlow<LinkMobileStep>
         get() = linkMobileStepFlow.asStateFlow()
 
+    /**
+     * Creates a new [LinkMobileHandler] and starts the linking process.
+     * If [forRotating] is true, it indicates that this is a rotation of the QR code.
+     *
+     * @param forRotating Whether this is a rotation of the QR code. Defaults to false.
+     */
     fun createAndStartNewHandler(forRotating: Boolean = false) {
         Timber.tag(loggerTag.value).d("createAndStartNewHandler()")
         currentJob?.cancel()
@@ -62,6 +72,10 @@ class LinkNewMobileHandler(
         }
     }
 
+    /**
+     * Resets the handler and cancels any ongoing job.
+     * This will also emit [LinkMobileStep.Uninitialized] to the [stepFlow].
+     */
     fun reset() {
         currentJob?.cancel()
         currentJob = null
@@ -70,10 +84,18 @@ class LinkNewMobileHandler(
         }
     }
 
+    /**
+     * Rotates the QR code by creating a new handler and starting the linking process.
+     * This is typically called when a timeout occurs for the current QR code.
+     */
     fun rotateQrCode() {
         createAndStartNewHandler(forRotating = true)
     }
 
+    /**
+     * Handles the case where there are too many QR code rotations.
+     * This will reset the handler and emit an error to the [stepFlow].
+     */
     fun onTooManyRotation() {
         reset()
         sessionScope.launch {