From 0a47aefdf70597334ffbbb6d1aebdc4ca3175966 Mon Sep 17 00:00:00 2001 From: Benoit Marty Date: Fri, 14 Aug 2026 09:57:38 +0200 Subject: [PATCH] Add KDoc to the `libraries/permissions` API interfaces Document PermissionsStore, PermissionStateProvider, LocalNetworkPermissionAdvisor and the PermissionsPresenter factory, along with their members and parameters. The store doc explains why the module exists: Android does not let an app distinguish "never asked" from "asked and denied", so the app has to remember that itself in order to decide whether it may show a rationale. Co-Authored-By: Claude Opus 5 (1M context) --- .../api/PermissionStateProvider.kt | 29 ++++++++++++++++++ .../permissions/api/PermissionsPresenter.kt | 6 ++++ .../permissions/api/PermissionsStore.kt | 30 +++++++++++++++++++ .../LocalNetworkPermissionAdvisor.kt | 5 ++++ 4 files changed, 70 insertions(+) diff --git a/libraries/permissions/api/src/main/kotlin/io/element/android/libraries/permissions/api/PermissionStateProvider.kt b/libraries/permissions/api/src/main/kotlin/io/element/android/libraries/permissions/api/PermissionStateProvider.kt index beeef0b234..98fb3edbe0 100644 --- a/libraries/permissions/api/src/main/kotlin/io/element/android/libraries/permissions/api/PermissionStateProvider.kt +++ b/libraries/permissions/api/src/main/kotlin/io/element/android/libraries/permissions/api/PermissionStateProvider.kt @@ -10,11 +10,40 @@ package io.element.android.libraries.permissions.api import kotlinx.coroutines.flow.Flow +/** + * Answers permission questions by combining the live system state with what [PermissionsStore] remembers about past requests. + */ interface PermissionStateProvider { + /** + * Whether the permission is granted right now, read from the system rather than from the store. + * + * @param permission the Android permission name. + */ fun isPermissionGranted(permission: String): Boolean + + /** + * @param permission the Android permission name. + * @param value true once the user has refused this permission. + */ suspend fun setPermissionDenied(permission: String, value: Boolean) + + /** + * Whether the user has refused this permission before. + * + * @param permission the Android permission name. + */ fun isPermissionDenied(permission: String): Flow + /** + * @param permission the Android permission name. + * @param value true once the system dialog for this permission has been shown. + */ suspend fun setPermissionAsked(permission: String, value: Boolean) + + /** + * Whether the system dialog for this permission has already been shown. + * + * @param permission the Android permission name. + */ fun isPermissionAsked(permission: String): Flow } diff --git a/libraries/permissions/api/src/main/kotlin/io/element/android/libraries/permissions/api/PermissionsPresenter.kt b/libraries/permissions/api/src/main/kotlin/io/element/android/libraries/permissions/api/PermissionsPresenter.kt index f2ccb2bfc3..07918d0c86 100644 --- a/libraries/permissions/api/src/main/kotlin/io/element/android/libraries/permissions/api/PermissionsPresenter.kt +++ b/libraries/permissions/api/src/main/kotlin/io/element/android/libraries/permissions/api/PermissionsPresenter.kt @@ -11,7 +11,13 @@ package io.element.android.libraries.permissions.api import io.element.android.libraries.architecture.Presenter interface PermissionsPresenter : Presenter { + /** + * Creates a presenter dedicated to one permission. + */ interface Factory { + /** + * @param permission the Android permission name this presenter will request. + */ fun create(permission: String): PermissionsPresenter } } diff --git a/libraries/permissions/api/src/main/kotlin/io/element/android/libraries/permissions/api/PermissionsStore.kt b/libraries/permissions/api/src/main/kotlin/io/element/android/libraries/permissions/api/PermissionsStore.kt index 3bb7d2c679..0bf7f0aefd 100644 --- a/libraries/permissions/api/src/main/kotlin/io/element/android/libraries/permissions/api/PermissionsStore.kt +++ b/libraries/permissions/api/src/main/kotlin/io/element/android/libraries/permissions/api/PermissionsStore.kt @@ -10,15 +10,45 @@ package io.element.android.libraries.permissions.api import kotlinx.coroutines.flow.Flow +/** + * Remembers what the app has already asked the user about, since Android itself does not let an app tell + * "never asked" apart from "asked and denied". + */ interface PermissionsStore { + /** + * @param permission the Android permission name. + * @param value true once the user has refused this permission. + */ suspend fun setPermissionDenied(permission: String, value: Boolean) + + /** + * Whether the user has refused this permission before. + * + * @param permission the Android permission name. + */ fun isPermissionDenied(permission: String): Flow + /** + * @param permission the Android permission name. + * @param value true once the system dialog for this permission has been shown. + */ suspend fun setPermissionAsked(permission: String, value: Boolean) + + /** + * Whether the system dialog for this permission has already been shown, which decides whether the app may show a rationale instead. + * + * @param permission the Android permission name. + */ fun isPermissionAsked(permission: String): Flow + /** + * Forgets what was recorded about one permission, so the app behaves as if it had never been requested. + * + * @param permission the Android permission name. + */ suspend fun resetPermission(permission: String) + /** Forgets every recorded permission; exposed for debugging from the developer options. */ // To debug suspend fun resetStore() } diff --git a/libraries/permissions/api/src/main/kotlin/io/element/android/libraries/permissions/api/localnetwork/LocalNetworkPermissionAdvisor.kt b/libraries/permissions/api/src/main/kotlin/io/element/android/libraries/permissions/api/localnetwork/LocalNetworkPermissionAdvisor.kt index 9863dbb751..8d801cfe67 100644 --- a/libraries/permissions/api/src/main/kotlin/io/element/android/libraries/permissions/api/localnetwork/LocalNetworkPermissionAdvisor.kt +++ b/libraries/permissions/api/src/main/kotlin/io/element/android/libraries/permissions/api/localnetwork/LocalNetworkPermissionAdvisor.kt @@ -7,10 +7,15 @@ package io.element.android.libraries.permissions.api.localnetwork +/** + * Decides whether the local network permission is needed to reach a homeserver, which is the case for a server on the user's own network. + */ interface LocalNetworkPermissionAdvisor { /** * Returns true when the app should request the ACCESS_LOCAL_NETWORK permission before making * network requests to [homeserverUrl]. + * + * @param homeserverUrl the server the app is about to contact. */ suspend fun shouldRequestPermissionFor(homeserverUrl: String): Boolean }