add documentation for remote config, crashlytics and database

firebase-config/src/commonMain/kotlin/dev/gitlive/firebase/remoteconfig/FirebaseRemoteConfig.kt

@@ -4,22 +4,127 @@ import dev.gitlive.firebase.Firebase
 import dev.gitlive.firebase.FirebaseApp
 import dev.gitlive.firebase.FirebaseException
 
+/** Returns the [FirebaseRemoteConfig] instance of the default [FirebaseApp]. */
 expect val Firebase.remoteConfig: FirebaseRemoteConfig
 
+/** Returns the [FirebaseRemoteConfig] instance of a given [FirebaseApp]. */
 expect fun Firebase.remoteConfig(app: FirebaseApp): FirebaseRemoteConfig
 
+/**
+ * Entry point for the Firebase Remote Config API.
+ *
+ * Callers should first get the singleton object using [Firebase.remoteConfig], and then call
+ * operations on that singleton object. The singleton contains the complete set of Remote Config
+ * parameter values available to your app. The singleton also stores values fetched from the Remote
+ * Config server until they are made available for use with a call to [activate].
+ */
 expect class FirebaseRemoteConfig {
+    /**
+     * Returns a [Map] of Firebase Remote Config key value pairs.
+     *
+     * Evaluates the values of the parameters in the following order:
+     *
+     * - The activated value, if the last successful [activate] contained the key.
+     * - The default value, if the key was set with [setDefaults].
+     */
     val all: Map<String, FirebaseRemoteConfigValue>
+
+    /**
+     * Returns the state of this [FirebaseRemoteConfig] instance as a [FirebaseRemoteConfigInfo].
+     */
     val info: FirebaseRemoteConfigInfo
 
+    /**
+     * Asynchronously activates the most recently fetched configs, so that the fetched key value pairs
+     * take effect.
+     *
+     * @return true result if the current call activated the fetched
+     *     configs; if the fetched configs were already activated by a previous call, it instead
+     *     returns a false result.
+     */
     suspend fun activate(): Boolean
+
+    /**
+     * Ensures the last activated config are available to the app.
+     */
     suspend fun ensureInitialized()
+
+    /**
+     * Starts fetching configs, adhering to the specified minimum fetch interval.
+     *
+     * The fetched configs only take effect after the next [activate] call.
+     *
+     * Depending on the time elapsed since the last fetch from the Firebase Remote Config backend,
+     * configs are either served from local storage, or fetched from the backend.
+     *
+     * Note: Also initializes the Firebase installations SDK that creates installation IDs to
+     * identify Firebase installations and periodically sends data to Firebase servers. Remote Config
+     * requires installation IDs for Fetch requests. To stop the periodic sync, call [FirebaseInstallations.delete]. Sending a Fetch request
+     * after deletion will create a new installation ID for this Firebase installation and resume the
+     * periodic sync.
+     *
+     * @param minimumFetchIntervalInSeconds If configs in the local storage were fetched more than
+     *     this many seconds ago, configs are served from the backend instead of local storage.
+     */
     suspend fun fetch(minimumFetchIntervalInSeconds: Long? = null)
+
+    /**
+     * Asynchronously fetches and then activates the fetched configs.
+     *
+     * If the time elapsed since the last fetch from the Firebase Remote Config backend is more
+     * than the default minimum fetch interval, configs are fetched from the backend.
+     *
+     * After the fetch is complete, the configs are activated so that the fetched key value pairs
+     * take effect.
+     *
+     * @return [Boolean] with a true result if the current call activated the fetched
+     *     configs; if no configs were fetched from the backend and the local fetched configs have
+     *     already been activated, returns a [Boolean] with a false result.
+     */
     suspend fun fetchAndActivate(): Boolean
+
+    /**
+     * Returns a [Set] of all Firebase Remote Config parameter keys with the given prefix.
+     *
+     * @param prefix The key prefix to look for. If the prefix is empty, all keys are returned.
+     * @return [Set] of Remote Config parameter keys that start with the specified prefix.
+     */
     fun getKeysByPrefix(prefix: String): Set<String>
+
+    /**
+     * Returns the parameter value for the given key as a [FirebaseRemoteConfigValue].
+     *
+     * Evaluates the value of the parameter in the following order:
+     *
+     * - The activated value, if the last successful [activate] contained the key.
+     * - The default value, if the key was set with [setDefaults].
+     * - A [FirebaseRemoteConfigValue] that returns the static value for each type.
+     *
+     * @param key A Firebase Remote Config parameter key.
+     * @return [FirebaseRemoteConfigValue] representing the value of the Firebase Remote Config
+     *     parameter with the given key.
+     */
     fun getValue(key: String): FirebaseRemoteConfigValue
+
+    /**
+     * Deletes all activated, fetched and defaults configs and resets all Firebase Remote Config
+     * settings.
+     */
     suspend fun reset()
+
+    /**
+     * Asynchronously changes the settings for this [FirebaseRemoteConfig] instance.
+     *
+     * @param init A builder to set the settings.
+     */
     suspend fun settings(init: FirebaseRemoteConfigSettings.() -> Unit)
+
+    /**
+     * Asynchronously sets default configs using the given [Map].
+     *
+     * @param defaults [Map] of key value pairs representing Firebase Remote Config parameter
+     *     keys and values.
+     */
     suspend fun setDefaults(vararg defaults: Pair<String, Any?>)
 }
 
@@ -36,7 +141,22 @@ inline operator fun <reified T> FirebaseRemoteConfig.get(key: String): T {
     } as T
 }
 
+/**
+ * Exception that gets thrown when an operation on Firebase Remote Config fails.
+ */
 expect open class FirebaseRemoteConfigException : FirebaseException
+
+/**
+ * Exception that gets thrown when an operation on Firebase Remote Config fails.
+ */
 expect class FirebaseRemoteConfigClientException : FirebaseRemoteConfigException
+
+/**
+ * Exception that gets thrown when an operation on Firebase Remote Config fails.
+ */
 expect class FirebaseRemoteConfigFetchThrottledException : FirebaseRemoteConfigException
+
+/**
+ * Exception that gets thrown when an operation on Firebase Remote Config fails.
+ */
 expect class FirebaseRemoteConfigServerException : FirebaseRemoteConfigException

firebase-config/src/commonMain/kotlin/dev/gitlive/firebase/remoteconfig/FirebaseRemoteConfigInfo.kt

@@ -1,9 +1,53 @@
 package dev.gitlive.firebase.remoteconfig
 
+/** Wraps the current state of the [FirebaseRemoteConfig] singleton object. */
 data class FirebaseRemoteConfigInfo(
+    /**
+     * Gets the current settings of the [FirebaseRemoteConfig] singleton object.
+     *
+     * @return A [FirebaseRemoteConfig] object indicating the current settings.
+     */
     val configSettings: FirebaseRemoteConfigSettings,
+
+    /**
+     * Gets the timestamp (milliseconds since epoch) of the last successful fetch, regardless of
+     * whether the fetch was activated or not.
+     *
+     * @return -1 if no fetch attempt has been made yet. Otherwise, returns the timestamp of the last
+     *     successful fetch operation.
+     */
     val fetchTimeMillis: Long,
+
+    /**
+     * Gets the status of the most recent fetch attempt.
+     *
+     * @return Will return one of [FetchStatus.Success], [FetchStatus.Failure], [FetchStatus.Throttled], or [FetchStatus.NoFetchYet]
+     */
     val lastFetchStatus: FetchStatus,
 )
 
-enum class FetchStatus { Success, Failure, Throttled, NoFetchYet }
+enum class FetchStatus {
+    /**
+     * Indicates that the most recent fetch of parameter values from the Firebase Remote Config server
+     * was completed successfully.
+     */
+    Success,
+
+    /**
+     * Indicates that the most recent attempt to fetch parameter values from the Firebase Remote
+     * Config server has failed.
+     */
+    Failure,
+
+    /**
+     * Indicates that the most recent attempt to fetch parameter values from the Firebase Remote
+     * Config server was throttled.
+     */
+    Throttled,
+
+    /**
+     * Indicates that the FirebaseRemoteConfig singleton object has not yet attempted to fetch
+     * parameter values from the Firebase Remote Config server.
+     */
+    NoFetchYet
+}

firebase-config/src/commonMain/kotlin/dev/gitlive/firebase/remoteconfig/FirebaseRemoteConfigSettings.kt

@@ -5,7 +5,16 @@ private const val CONNECTION_TIMEOUT_IN_SECONDS = 60L
 // https://firebase.google.com/docs/remote-config/get-started?hl=en&platform=android#throttling
 private const val DEFAULT_FETCH_INTERVAL_IN_SECONDS = 12 * 3600L
 
+/** Wraps the settings for [FirebaseRemoteConfig] operations. */
 data class FirebaseRemoteConfigSettings(
+    /**
+     * Returns the fetch timeout in seconds.
+     *
+     * The timeout specifies how long the client should wait for a connection to the Firebase
+     * Remote Config server.
+     */
     var fetchTimeoutInSeconds: Long = CONNECTION_TIMEOUT_IN_SECONDS,
+
+    /** Returns the minimum interval between successive fetches calls in seconds. */
     var minimumFetchIntervalInSeconds: Long = DEFAULT_FETCH_INTERVAL_IN_SECONDS,
 )

firebase-config/src/commonMain/kotlin/dev/gitlive/firebase/remoteconfig/FirebaseRemoteConfigValue.kt

@@ -1,12 +1,57 @@
 package dev.gitlive.firebase.remoteconfig
 
+/** Wrapper for a Remote Config parameter value, with methods to get it as different types. */
 expect class FirebaseRemoteConfigValue {
+    /**
+     * Gets the value as a [Boolean].
+     *
+     * @return [Boolean] representation of this parameter value.
+     */
     fun asBoolean(): Boolean
+
+    /**
+     * Gets the value as a [ByteArray].
+     *
+     * @return [ByteArray] representation of this parameter value.
+     */
     fun asByteArray(): ByteArray
+
+    /**
+     * Gets the value as a [Double].
+     *
+     * @return [Double] representation of this parameter value.
+     */
     fun asDouble(): Double
+
+    /**
+     * Gets the value as a [Long].
+     *
+     * @return [Long] representation of this parameter value.
+     */
     fun asLong(): Long
+
+    /**
+     * Gets the value as a [String].
+     *
+     * @return [String] representation of this parameter value.
+     */
     fun asString(): String
+
+    /**
+     * Indicates at which source this value came from.
+     *
+     * @return [ValueSource.Remote] if the value was retrieved from the server, [ValueSource.Default] if the value was set as a default, or [ValueSource.Stataic] if no value was found and a static default value was returned instead.
+     */
     fun getSource(): ValueSource
 }
 
-enum class ValueSource { Static, Default, Remote }
+enum class ValueSource {
+    /** Indicates that the value returned is the static default value. */
+    Static,
+
+    /** Indicates that the value returned was retrieved from the defaults set by the client. */
+    Default,
+
+    /** Indicates that the value returned was retrieved from the Firebase Remote Config server. */
+    Remote
+}