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

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<Boolean>
 
+    /**
+     * @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<Boolean>
 }

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<PermissionsState> {
+    /**
+     * Creates a presenter dedicated to one permission.
+     */
     interface Factory {
+        /**
+         * @param permission the Android permission name this presenter will request.
+         */
         fun create(permission: String): PermissionsPresenter
     }
 }

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<Boolean>
 
+    /**
+     * @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<Boolean>
 
+    /**
+     * 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()
 }

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
 }