From d80aaf6be4959c453d1f5f77e6f800f090d68ad1 Mon Sep 17 00:00:00 2001
From: Benoit Marty <benoit@matrix.org>
Date: Fri, 14 Aug 2026 11:24:05 +0200
Subject: [PATCH] Add KDoc to the `libraries/mediapickers` API interfaces

Document PickerProvider and each of its register methods.

The interface doc carries the two rules that apply to all of them: they must be
called during composition rather than from a click handler, and a cancelled pick
arrives as a null uri or an empty list rather than as an error.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 .../mediapickers/api/PickerProvider.kt        | 42 +++++++++++++++++++
 1 file changed, 42 insertions(+)

diff --git a/libraries/mediapickers/api/src/main/kotlin/io/element/android/libraries/mediapickers/api/PickerProvider.kt b/libraries/mediapickers/api/src/main/kotlin/io/element/android/libraries/mediapickers/api/PickerProvider.kt
index 1bab693609..185b2f58a0 100644
--- a/libraries/mediapickers/api/src/main/kotlin/io/element/android/libraries/mediapickers/api/PickerProvider.kt
+++ b/libraries/mediapickers/api/src/main/kotlin/io/element/android/libraries/mediapickers/api/PickerProvider.kt
@@ -12,37 +12,79 @@ import android.net.Uri
 import androidx.activity.result.PickVisualMediaRequest
 import androidx.compose.runtime.Composable
 
+/**
+ * Registers the system media and file pickers from Composable code, returning launchers the UI can trigger later.
+ *
+ * Every method must be called during composition, not from a click handler; a cancelled pick reports a `null` uri or an empty list.
+ */
 interface PickerProvider {
+    /**
+     * Registers a picker for a single photo or video from the gallery.
+     *
+     * @param onResult called with the picked media and its MIME type, both `null` when the user cancelled.
+     */
     @Composable
     fun registerGalleryPicker(
         onResult: (uri: Uri?, mimeType: String?) -> Unit
     ): PickerLauncher<PickVisualMediaRequest, Uri?>
 
+    /**
+     * Registers a picker restricted to a single image, used where a video would not be valid, such as for an avatar.
+     *
+     * @param onResult called with the picked image, `null` when the user cancelled.
+     */
     @Composable
     fun registerGalleryImagePicker(
         onResult: (Uri?) -> Unit
     ): PickerLauncher<PickVisualMediaRequest, Uri?>
 
+    /**
+     * Registers a picker for several photos or videos at once.
+     *
+     * @param onResult called with the picked media, empty when the user cancelled.
+     */
     @Composable
     fun registerGalleryMultiPicker(
         onResult: (uris: List<Uri>) -> Unit
     ): PickerLauncher<PickVisualMediaRequest, List<Uri>>
 
+    /**
+     * Registers a picker for a single file of any kind.
+     *
+     * @param mimeType the MIME type to filter on, `*` / `*` to accept anything.
+     * @param onResult called with the picked file and its MIME type, both `null` when the user cancelled.
+     */
     @Composable
     fun registerFilePicker(
         mimeType: String,
         onResult: (uri: Uri?, mimeType: String?) -> Unit,
     ): PickerLauncher<String, Uri?>
 
+    /**
+     * Registers a picker for several files at once.
+     *
+     * @param mimeType the MIME type to filter on.
+     * @param onResult called with the picked files, empty when the user cancelled.
+     */
     @Composable
     fun registerFileMultiPicker(
         mimeType: String,
         onResult: (uris: List<Uri>) -> Unit,
     ): PickerLauncher<Array<String>, List<Uri>>
 
+    /**
+     * Registers a launcher that opens the camera to take a photo.
+     *
+     * @param onResult called with the captured photo, `null` when the user cancelled or the capture failed.
+     */
     @Composable
     fun registerCameraPhotoPicker(onResult: (Uri?) -> Unit): PickerLauncher<Uri, Boolean>
 
+    /**
+     * Registers a launcher that opens the camera to record a video.
+     *
+     * @param onResult called with the recorded video, `null` when the user cancelled or the capture failed.
+     */
     @Composable
     fun registerCameraVideoPicker(onResult: (Uri?) -> Unit): PickerLauncher<Uri, Boolean>
 }