Add KDoc to the single-interface feature API modules

Cover the last remaining interfaces across features/announcement, cachecleaner, call, contentscanner, createroom, knockrequests, lockscreen, rolesandpermissions, startchat, userprofile and viewfolder, with their members and parameters. Grouped into one commit rather than eleven near-empty ones, per the AGENTS.md rule about tiny commits. This completes every features/* api module. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-10-31 16:22:49 +00:00 · 2026-08-14 12:00:42 +02:00
parent 1b4d6c07fa
commit 9822b3d4f7
11 changed files with 85 additions and 0 deletions
@@ -12,15 +12,34 @@ import androidx.compose.runtime.Composable
 import androidx.compose.ui.Modifier
 import kotlinx.coroutines.flow.Flow

+/**
+ * Queues the full-screen announcements shown to the user once, such as the notice about a new feature.
+ *
+ * A dismissed announcement is remembered so it is not shown again.
+ */
 interface AnnouncementService {
+    /**
+     * Queues an announcement, unless the user has already dismissed it.
+     *
+     * @param announcement the announcement to show.
+     */
    suspend fun showAnnouncement(announcement: Announcement)

+    /**
+     * Records that the user dismissed an announcement, so it is not queued again.
+     *
+     * @param announcement the announcement that was dismissed.
+     */
    suspend fun onAnnouncementDismissed(announcement: Announcement)

+    /** The announcements still waiting to be shown, in the order they should appear. */
    fun announcementsToShowFlow(): Flow<List<Announcement>>

    /**
     * Use this composable to render the announcement UI in Fullscreen.
+     * Draws nothing while there is no announcement to show.
+     *
+     * @param modifier layout modifier for the container.
     */
    @Composable
    fun Render(
@@ -8,6 +8,9 @@

 package io.element.android.features.cachecleaner.api

+/**
+ * Removes the temporary files holding decrypted content, so plaintext media does not linger on disk.
+ */
 interface CacheCleaner {
    /**
     * Clear the cache subdirs holding temporarily decrypted content (such as media and voice messages).
@@ -10,6 +10,9 @@ package io.element.android.features.call.api

 import kotlinx.coroutines.flow.StateFlow

+/**
+ * Tracks the call the user is currently in on this device, so unrelated parts of the app can react to it.
+ */
 interface CurrentCallService {
    /**
     * The current call state flow, which will be updated when the active call changes.
@@ -18,5 +18,11 @@ import io.element.android.libraries.matrix.ui.media.contentvalidation.ContentVal
 * This will only process media when a [ContentScanner] is provided when building the client in Pro.
 */
 fun interface ContentScannerService {
+    /**
+     * Starts scanning the given media, reporting the verdict of each one through [contentValidationState] rather than by returning.
+     *
+     * @param mediaSources the media to scan.
+     * @param contentValidationState where the outcome of each scan is published for the UI to observe.
+     */
    fun scan(mediaSources: List<MediaSource>, contentValidationState: ContentValidationState)
 }
@@ -15,9 +15,21 @@ import io.element.android.libraries.architecture.FeatureEntryPoint
 import io.element.android.libraries.matrix.api.core.RoomId

 interface CreateRoomEntryPoint : FeatureEntryPoint {
+    /**
+     * Configures the create-room flow before it is started, since it serves rooms and spaces from the same screens.
+     */
    interface Builder {
+        /**
+         * @param isSpace true to create a space rather than a room.
+         */
        fun setIsSpace(isSpace: Boolean): Builder
+
+        /**
+         * @param parentSpaceId the space the new room should be added to once created.
+         */
        fun setParentSpace(parentSpaceId: RoomId): Builder
+
+        /** Builds the node with the options configured so far. */
        fun build(): Node
    }

@@ -11,7 +11,16 @@ package io.element.android.features.knockrequests.api.banner
 import androidx.compose.runtime.Composable
 import androidx.compose.ui.Modifier

+/**
+ * Renders the banner shown at the top of a room when people are waiting to join it.
+ */
 interface KnockRequestsBannerRenderer {
+    /**
+     * Draws the banner, or nothing when there is no pending request or the user cannot moderate the room.
+     *
+     * @param modifier layout modifier for the container.
+     * @param onViewRequestsClick called when the user asks to see the full list of requests.
+     */
    @Composable
    fun View(modifier: Modifier, onViewRequestsClick: () -> Unit)
 }
@@ -17,6 +17,9 @@ import kotlinx.coroutines.flow.StateFlow
 import kotlinx.coroutines.flow.launchIn
 import kotlinx.coroutines.flow.onEach

+/**
+ * Exposes the app lock state: whether a PIN or biometric lock is set up, whether it is mandatory, and whether the app is locked right now.
+ */
 interface LockScreenService {
    /**
     * The current lock state of the app.
@@ -22,8 +22,18 @@ fun interface ChangeRoomMemberRolesEntryPoint : FeatureEntryPoint {
        listType: ChangeRoomMemberRolesListType,
    ): Node

+    /**
+     * Lets a caller outside this feature wait for the role change to finish, which is needed when leaving a room depends on it.
+     */
    interface NodeProxy {
+        /** The room whose member roles are being changed. */
        val roomId: RoomId
+
+        /**
+         * Suspends until the user finishes or abandons the flow.
+         *
+         * @return true when roles were actually changed, false when the user backed out.
+         */
        suspend fun waitForCompletion(): Boolean
    }
 }
@@ -13,6 +13,11 @@ import io.element.android.libraries.architecture.AsyncAction
 import io.element.android.libraries.matrix.api.core.RoomId
 import io.element.android.libraries.matrix.api.user.MatrixUser

+/**
+ * Opens a direct message with a user, reusing the existing room when there is one.
+ *
+ * Progress is reported into the state passed in, so the caller only has to render it.
+ */
 interface StartDMAction {
    /**
     * Try to find an existing DM with the given user, or create one if none exists.
@@ -11,6 +11,12 @@ package io.element.android.features.userprofile.api
 import io.element.android.libraries.architecture.Presenter
 import io.element.android.libraries.matrix.api.core.UserId

+/**
+ * Creates the user profile presenter, so that other features can show a profile without depending on this one's implementation.
+ */
 fun interface UserProfilePresenterFactory {
+    /**
+     * @param userId the user whose profile is shown.
+     */
    fun create(userId: UserId): Presenter<UserProfileState>
 }
@@ -12,7 +12,16 @@ import androidx.compose.runtime.Composable
 import androidx.compose.ui.Modifier
 import kotlinx.collections.immutable.ImmutableList

+/**
+ * Renders the contents of a text file, used by the log viewer in the developer options.
+ */
 fun interface TextFileViewer {
+    /**
+     * Draws the file, one row per line.
+     *
+     * @param lines the already-read contents of the file.
+     * @param modifier layout modifier for the container.
+     */
    @Composable
    fun Render(
        lines: ImmutableList<String>,