Add KDoc to the features/enterprise API interfaces

Document EnterpriseService, SessionEnterpriseService and
RemoteEnterpriseConfigProvider along with all their members and parameters.

Two points that callers get wrong are stated explicitly: these services return
permissive defaults on a standard build, so there is no need to branch on the
build type, and SessionEnterpriseService only answers meaningfully once init has
run. The many nullable getters now say what null means in each case, which is
generally "no override, use the app default".

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

features/enterprise/api/src/main/kotlin/io/element/android/features/enterprise/api/EnterpriseService.kt

@@ -15,11 +15,41 @@ import io.element.android.libraries.matrix.api.core.SessionId
 import io.element.android.libraries.wellknown.api.ElementWellKnown
 import kotlinx.coroutines.flow.Flow
 
+/**
+ * Exposes the restrictions and customisations an enterprise deployment can impose: allowed homeservers, branding, push gateways and more.
+ *
+ * On a standard build this reports permissive defaults, so callers do not need to branch on the build type themselves.
+ */
 interface EnterpriseService {
+    /** Whether this build is an enterprise one; `false` for the public app. */
     val isEnterpriseBuild: Boolean
+
+    /**
+     * Whether the given session belongs to an enterprise deployment, which can be true even on a standard build.
+     *
+     * @param sessionId the session to check.
+     */
     suspend fun isEnterpriseUser(sessionId: SessionId): Boolean
+
+    /**
+     * Rewrites the authentication server URL when the deployment requires a different one from the one advertised.
+     *
+     * @param url the URL to rewrite.
+     * @param homeserver the homeserver the URL belongs to.
+     * @param urlContentFetcher used to read the deployment configuration; a client that is not authenticated yet also works.
+     */
     suspend fun tweakMasUrl(url: String, homeserver: String, urlContentFetcher: UrlContentFetcher): String
+
+    /**
+     * The homeservers the user is allowed to sign in to; an empty list, or one containing [ANY_ACCOUNT_PROVIDER], means no restriction.
+     */
     fun defaultHomeserverList(): List<String>
+
+    /**
+     * Whether the user is allowed to sign in to a given homeserver, according to [defaultHomeserverList].
+     *
+     * @param homeserverUrl the server the user is trying to use.
+     */
     suspend fun isAllowedToConnectToHomeserver(homeserverUrl: String): Boolean
 
     /**
@@ -29,17 +59,38 @@ interface EnterpriseService {
      */
     suspend fun overrideBrandColor(sessionId: SessionId?, brandColor: String?)
 
+    /**
+     * The brand color to apply, or `null` when the default theme color should be used.
+     *
+     * @param sessionId the session to read the color of, or `null` for the color used when no session is active.
+     */
     fun brandColorsFlow(sessionId: SessionId?): Flow<Color?>
 
+    /**
+     * The full light and dark color palettes derived from the brand color.
+     *
+     * @param sessionId the session to read the colors of, or `null` for the colors used when no session is active.
+     */
     fun semanticColorsFlow(sessionId: SessionId?): Flow<SemanticColorsLightDark>
 
+    /** The push gateway to register with when using Firebase, or `null` to use the app default. */
     fun firebasePushGateway(): String?
+
+    /** The push gateway to register with when using UnifiedPush, or `null` to use the app default. */
     fun unifiedPushDefaultPushGateway(): String?
 
+    /**
+     * Where bug reports should be submitted, which an enterprise deployment can redirect or disable entirely.
+     *
+     * @param sessionId the session to read the setting of, or `null` for the setting used when no session is active.
+     */
     fun bugReportUrlFlow(sessionId: SessionId?): Flow<BugReportUrl>
 
     /**
      * Gets Notification Channel to use for the noisy notifications of the provided session.
+     * Returns `null` when the session has no dedicated channel and the app-wide one should be used.
+     *
+     * @param sessionId the session whose channel is requested.
      */
     fun getNoisyNotificationChannelId(sessionId: SessionId): String?
 
@@ -50,6 +101,9 @@ interface EnterpriseService {
 
     /**
      * Gets the Element Server Suite (ESS) config endpoint URL for the given domain.
+     * Returns `null` when this build does not read its configuration from an ESS deployment.
+     *
+     * @param domain the server whose configuration endpoint is requested.
      */
     fun essConfigEndpointUrl(domain: String): String?
 

features/enterprise/api/src/main/kotlin/io/element/android/features/enterprise/api/SessionEnterpriseService.kt

@@ -8,11 +8,25 @@
 
 package io.element.android.features.enterprise.api
 
+/**
+ * The session-scoped counterpart of [EnterpriseService], answering the same kind of questions for the session it belongs to.
+ *
+ * [init] must have run before the other members return meaningful answers.
+ */
 interface SessionEnterpriseService {
+    /** Whether Element Call may be used on this session, which a deployment can turn off. */
     suspend fun isElementCallAvailable(): Boolean
+
+    /**
+     * Rewrites the authentication server URL for this session; see [EnterpriseService.tweakMasUrl].
+     *
+     * @param url the URL to rewrite.
+     */
     suspend fun tweakMasUrl(url: String): String
 
+    /** Whether the homeserver forbids creating encrypted rooms, in which case the app must not offer the option. */
     suspend fun isEncryptionDisabledByHomeserver(): Boolean
 
+    /** Loads the deployment configuration of this session; to be called once when the session starts. */
     suspend fun init()
 }

features/enterprise/api/src/main/kotlin/io/element/android/features/enterprise/api/remoteconfig/RemoteEnterpriseConfigProvider.kt

@@ -15,9 +15,21 @@ import io.element.android.libraries.wellknown.api.WellknownRetrieverResult
  * Wrapper to fetch the remote enterprise configuration for a given [SessionId], either from a local cache or from a remote source.
  */
 interface RemoteEnterpriseConfigProvider {
+    /**
+     * Returns the configuration of a session, served from the cache when possible.
+     * A stale entry is reported as outdated while a refresh runs in the background, so this rarely waits on the network.
+     *
+     * @param sessionId the session whose configuration is requested.
+     */
     suspend fun get(sessionId: SessionId): WellknownRetrieverResult<RemoteEnterpriseConfig>
 
+    /**
+     * Creates a provider, which needs a fetcher because the configuration is read over HTTP.
+     */
     interface Factory {
+        /**
+         * @param urlContentFetcher used to perform the request; a client that is not authenticated yet also works.
+         */
         fun create(urlContentFetcher: UrlContentFetcher): RemoteEnterpriseConfigProvider
     }
 }