From c0848cee9d7b8a2ef9670dc3ddf0e5ccd2d8a2b7 Mon Sep 17 00:00:00 2001
From: Benoit Marty <benoit@matrix.org>
Date: Fri, 14 Aug 2026 10:28:47 +0200
Subject: [PATCH] Add KDoc to the `libraries/deeplink` API interfaces

Document DeeplinkParser, DeepLinkCreator and InviteFriendsUseCase, including that
DeepLinkCreator.create silently ignores the deeper arguments once an outer one is
null.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../android/libraries/deeplink/api/DeepLinkCreator.kt | 11 +++++++++++
 .../android/libraries/deeplink/api/DeeplinkParser.kt  |  7 +++++++
 .../deeplink/api/usecase/InviteFriendsUseCase.kt      |  6 ++++++
 3 files changed, 24 insertions(+)

diff --git a/libraries/deeplink/api/src/main/kotlin/io/element/android/libraries/deeplink/api/DeepLinkCreator.kt b/libraries/deeplink/api/src/main/kotlin/io/element/android/libraries/deeplink/api/DeepLinkCreator.kt
index 2b46b15e46..938939c6f0 100644
--- a/libraries/deeplink/api/src/main/kotlin/io/element/android/libraries/deeplink/api/DeepLinkCreator.kt
+++ b/libraries/deeplink/api/src/main/kotlin/io/element/android/libraries/deeplink/api/DeepLinkCreator.kt
@@ -13,6 +13,17 @@ import io.element.android.libraries.matrix.api.core.RoomId
 import io.element.android.libraries.matrix.api.core.SessionId
 import io.element.android.libraries.matrix.api.core.ThreadId
 
+/**
+ * Builds the app's internal deep links, used to point a notification or a shortcut at a precise place in the app.
+ */
 fun interface DeepLinkCreator {
+    /**
+     * Builds a link to the most precise target the arguments allow, ignoring the deeper ones once an outer one is `null`.
+     *
+     * @param sessionId the session to open.
+     * @param roomId the room to open, or `null` to stop at the room list.
+     * @param threadId the thread to open within that room, or `null` for the main timeline.
+     * @param eventId the event to focus on, or `null` to open at the latest message.
+     */
     fun create(sessionId: SessionId, roomId: RoomId?, threadId: ThreadId?, eventId: EventId?): String
 }
diff --git a/libraries/deeplink/api/src/main/kotlin/io/element/android/libraries/deeplink/api/DeeplinkParser.kt b/libraries/deeplink/api/src/main/kotlin/io/element/android/libraries/deeplink/api/DeeplinkParser.kt
index f0f8640a2d..7a711d8a3a 100644
--- a/libraries/deeplink/api/src/main/kotlin/io/element/android/libraries/deeplink/api/DeeplinkParser.kt
+++ b/libraries/deeplink/api/src/main/kotlin/io/element/android/libraries/deeplink/api/DeeplinkParser.kt
@@ -10,6 +10,13 @@ package io.element.android.libraries.deeplink.api
 
 import android.content.Intent
 
+/**
+ * Extracts the app's own deep link data from an incoming intent; see [DeepLinkCreator] for the other direction.
+ */
 fun interface DeeplinkParser {
+    /**
+     * @param intent the intent the app was started or resumed with.
+     * @return the session, room and event to open, or `null` when the intent is not one of the app's deep links.
+     */
     fun getFromIntent(intent: Intent): DeeplinkData?
 }
diff --git a/libraries/deeplink/api/src/main/kotlin/io/element/android/libraries/deeplink/api/usecase/InviteFriendsUseCase.kt b/libraries/deeplink/api/src/main/kotlin/io/element/android/libraries/deeplink/api/usecase/InviteFriendsUseCase.kt
index 64287f918c..2c4406a482 100644
--- a/libraries/deeplink/api/src/main/kotlin/io/element/android/libraries/deeplink/api/usecase/InviteFriendsUseCase.kt
+++ b/libraries/deeplink/api/src/main/kotlin/io/element/android/libraries/deeplink/api/usecase/InviteFriendsUseCase.kt
@@ -10,6 +10,12 @@ package io.element.android.libraries.deeplink.api.usecase
 
 import android.app.Activity
 
+/**
+ * Opens the system share sheet with an invitation to install the app.
+ */
 fun interface InviteFriendsUseCase {
+    /**
+     * @param activity the activity the share sheet is shown from.
+     */
     fun execute(activity: Activity)
 }