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) <noreply@anthropic.com>

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.

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
 
     /**

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<Unit>
 
     /**
      * 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<Unit>
 }

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.

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<String?>
 
+    /**
+     * 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
     }
 }