Merge pull request #7426 from element-hq/feature/bma/documentation

Add KDoc to all the interfaces of the api modules

libraries/wellknown/api/src/main/kotlin/io/element/android/libraries/wellknown/api/ElementWellKnownParser.kt

@@ -7,6 +7,14 @@
 
 package io.element.android.libraries.wellknown.api
 
+/**
+ * Parses the raw JSON of an Element `.well-known` document.
+ */
 fun interface ElementWellKnownParser {
+    /**
+     * Parses the document, failing when it is not valid JSON; unknown fields are ignored so a newer server does not break an older client.
+     *
+     * @param json the raw document as served by the server.
+     */
     fun parse(json: String): Result<ElementWellKnown>
 }

libraries/wellknown/api/src/main/kotlin/io/element/android/libraries/wellknown/api/ElementWellknownStore.kt

@@ -7,12 +7,41 @@
 
 package io.element.android.libraries.wellknown.api
 
+/**
+ * On-disk cache of the Element `.well-known` documents already fetched, so the app has a configuration to work with while offline.
+ */
 interface ElementWellknownStore {
+    /**
+     * Reads the cached document of a domain.
+     * Entries older than a day are reported as outdated rather than missing, so the caller can use them while refreshing;
+     * a document that no longer parses is reported as an error.
+     *
+     * @param domain the server whose cached document is requested.
+     */
     suspend fun get(domain: String): WellknownRetrieverResult<ElementWellKnown>
+
+    /**
+     * Stores the document of a domain and stamps it as fetched now, replacing any previous entry.
+     *
+     * @param domain the server the document belongs to.
+     * @param wellknown the raw document, stored as-is rather than parsed.
+     */
     suspend fun update(domain: String, wellknown: String): Result<Unit>
+
+    /**
+     * Removes the cached document of a domain, used when the stored value turns out to be unusable.
+     *
+     * @param domain the server whose entry is removed.
+     */
     suspend fun delete(domain: String): Result<Unit>
 
+    /**
+     * Creates a store, one per configuration source so that their entries never collide.
+     */
     fun interface Factory {
+        /**
+         * @param prefix namespaces the cache keys, or `null` for the default well-known endpoint.
+         */
         fun create(prefix: String?): ElementWellknownStore
     }
 }

libraries/wellknown/api/src/main/kotlin/io/element/android/libraries/wellknown/api/WellknownRetriever.kt

@@ -10,13 +10,30 @@ package io.element.android.libraries.wellknown.api
 
 import io.element.android.libraries.matrix.api.UrlContentFetcher
 
+/**
+ * Retrieves the Element specific `.well-known` configuration of a server, which is how a deployment advertises its own settings.
+ */
 interface WellknownRetriever {
+    /**
+     * Returns the configuration of a host, served from the local cache when possible.
+     * A cached value that has gone stale is returned as outdated while a refresh runs in the background, so this rarely waits on the network.
+     * An enterprise build with a hardcoded configuration always short-circuits and returns that instead.
+     *
+     * @param host the server to look up; a full URL is accepted and reduced to its host.
+     * @param source which endpoint to read the configuration from, which also selects the cache it is stored in.
+     */
     suspend fun getElementWellKnown(
         host: String,
         source: EnterpriseRemoteConfigSource
     ): WellknownRetrieverResult<ElementWellKnown>
 
+    /**
+     * Creates a retriever, 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): WellknownRetriever
     }
 }