From 68e5ea5a7427dde337cee1c46a4fb47f04f8f14c Mon Sep 17 00:00:00 2001 From: Benoit Marty Date: Thu, 13 Aug 2026 19:30:24 +0200 Subject: [PATCH] Add KDoc to matrix API media, mxc and scanner interfaces Add the interface level docs that MediaPreviewService, MatrixMediaLoader and MxcTools were missing, document MediaFile.path and the nested ContentScannerUrlProvider.Factory, and add the missing @param entries. Most members in these packages already had accurate documentation and are left untouched. Co-Authored-By: Claude Opus 5 (1M context) --- .../libraries/matrix/api/media/MatrixMediaLoader.kt | 3 +++ .../android/libraries/matrix/api/media/MediaFile.kt | 1 + .../libraries/matrix/api/media/MediaPreviewService.kt | 9 +++++++++ .../element/android/libraries/matrix/api/mxc/MxcTools.kt | 3 +++ .../matrix/api/scanner/ContentScannerUrlProvider.kt | 6 ++++++ 5 files changed, 22 insertions(+) diff --git a/libraries/matrix/api/src/main/kotlin/io/element/android/libraries/matrix/api/media/MatrixMediaLoader.kt b/libraries/matrix/api/src/main/kotlin/io/element/android/libraries/matrix/api/media/MatrixMediaLoader.kt index a36849b812..28ae0762ff 100644 --- a/libraries/matrix/api/src/main/kotlin/io/element/android/libraries/matrix/api/media/MatrixMediaLoader.kt +++ b/libraries/matrix/api/src/main/kotlin/io/element/android/libraries/matrix/api/media/MatrixMediaLoader.kt @@ -8,6 +8,9 @@ package io.element.android.libraries.matrix.api.media +/** + * Fetches media content from the homeserver, decrypting it on the way when the room is encrypted. + */ interface MatrixMediaLoader { /** * @param source to fetch the content for. diff --git a/libraries/matrix/api/src/main/kotlin/io/element/android/libraries/matrix/api/media/MediaFile.kt b/libraries/matrix/api/src/main/kotlin/io/element/android/libraries/matrix/api/media/MediaFile.kt index b5cefe897b..ae6035da88 100644 --- a/libraries/matrix/api/src/main/kotlin/io/element/android/libraries/matrix/api/media/MediaFile.kt +++ b/libraries/matrix/api/src/main/kotlin/io/element/android/libraries/matrix/api/media/MediaFile.kt @@ -16,6 +16,7 @@ import java.io.File * When closed the file will be removed from the disk unless [persist] has been used. */ interface MediaFile : Closeable { + /** The absolute path of the file on disk; see [toFile] to get a [File] instead. */ fun path(): String /** diff --git a/libraries/matrix/api/src/main/kotlin/io/element/android/libraries/matrix/api/media/MediaPreviewService.kt b/libraries/matrix/api/src/main/kotlin/io/element/android/libraries/matrix/api/media/MediaPreviewService.kt index 39718ddfd2..660bb0b80e 100644 --- a/libraries/matrix/api/src/main/kotlin/io/element/android/libraries/matrix/api/media/MediaPreviewService.kt +++ b/libraries/matrix/api/src/main/kotlin/io/element/android/libraries/matrix/api/media/MediaPreviewService.kt @@ -10,6 +10,11 @@ package io.element.android.libraries.matrix.api.media import kotlinx.coroutines.flow.StateFlow +/** + * Reads and writes the account settings that decide whether media previews and invite avatars are shown. + * + * These are account data settings shared across clients, so the local value is only updated once the server has accepted the change. + */ interface MediaPreviewService { /** * Will fetch the media preview config from the server. @@ -24,11 +29,15 @@ interface MediaPreviewService { /** * Set the media preview display policy. This will update the value on the server and update the local value when successful. + * + * @param mediaPreviewValue whether media previews are shown always, never, or only in private rooms. */ suspend fun setMediaPreviewValue(mediaPreviewValue: MediaPreviewValue): Result /** * Set the invite avatars display policy. This will update the value on the server and update the local value when successful. + * + * @param hide true to hide the avatars of users and rooms the user has been invited by. */ suspend fun setHideInviteAvatars(hide: Boolean): Result } diff --git a/libraries/matrix/api/src/main/kotlin/io/element/android/libraries/matrix/api/mxc/MxcTools.kt b/libraries/matrix/api/src/main/kotlin/io/element/android/libraries/matrix/api/mxc/MxcTools.kt index 09ceaa4712..c28bfa9933 100644 --- a/libraries/matrix/api/src/main/kotlin/io/element/android/libraries/matrix/api/mxc/MxcTools.kt +++ b/libraries/matrix/api/src/main/kotlin/io/element/android/libraries/matrix/api/mxc/MxcTools.kt @@ -8,6 +8,9 @@ package io.element.android.libraries.matrix.api.mxc +/** + * Helpers to work with Matrix Content (`mxc://`) URIs. + */ interface MxcTools { /** * Sanitizes an mxcUri to be used as a relative file path. diff --git a/libraries/matrix/api/src/main/kotlin/io/element/android/libraries/matrix/api/scanner/ContentScannerUrlProvider.kt b/libraries/matrix/api/src/main/kotlin/io/element/android/libraries/matrix/api/scanner/ContentScannerUrlProvider.kt index 76878080ae..2c11c750e4 100644 --- a/libraries/matrix/api/src/main/kotlin/io/element/android/libraries/matrix/api/scanner/ContentScannerUrlProvider.kt +++ b/libraries/matrix/api/src/main/kotlin/io/element/android/libraries/matrix/api/scanner/ContentScannerUrlProvider.kt @@ -19,7 +19,13 @@ fun interface ContentScannerUrlProvider { */ suspend fun getContentScannerUrl(sessionId: SessionId): Result + /** + * Creates a provider, which needs a fetcher because the scanner URL is itself discovered over HTTP. + */ fun interface Factory { + /** + * @param urlContentFetcher used to read the configuration advertised by the homeserver; a client that is not authenticated yet also works. + */ fun create(urlContentFetcher: UrlContentFetcher): ContentScannerUrlProvider } }