Added docs for some functions

Author: MrBoomDeveloper

core/src/androidMain/kotlin/com/mrboomdev/awery/core/utils/AndroidUtils.kt

@@ -4,6 +4,14 @@ import android.app.Activity
 import android.content.Context
 import android.content.ContextWrapper
 
+/**
+ * Attempts to retrieve the [Activity] associated with the given [Context].
+ * 
+ * This function traverses the context hierarchy until it finds an [Activity] or reaches the root context.
+ * If an [Activity] is found, it is returned. Otherwise, null is returned.
+ * 
+ * @return The associated [Activity], or null if none is found.
+ */
 fun Context.toActivity(): Activity? {
     var current = this
 

core/src/androidMain/kotlin/com/mrboomdev/awery/core/utils/PermissionUtils.kt

@@ -5,6 +5,11 @@ import android.os.Build
 import com.mrboomdev.awery.core.Awery
 import com.mrboomdev.awery.core.context
 
+/**
+ * Checks if the application has the specified permission.
+ * @param permission The permission to check for.
+ * @return True if the application has the permission, false otherwise.
+ */
 fun Awery.hasPermission(permission: AppPermission): Boolean {
 	if(permission.constant == null) return true
 

core/src/commonMain/kotlin/com/mrboomdev/awery/core/Awery.kt

@@ -1,19 +1,34 @@
 package com.mrboomdev.awery.core
 
-import io.ktor.client.HttpClient
-import io.ktor.client.HttpClientConfig
-import io.ktor.client.engine.cio.CIO
-import io.ktor.client.plugins.HttpTimeout
-import io.ktor.client.plugins.compression.ContentEncoding
+import io.ktor.client.*
+import io.ktor.client.engine.cio.*
+import io.ktor.client.plugins.*
+import io.ktor.client.plugins.compression.*
 
 /**
  * Main object, that stores all the global variables and functions.
  * Also, this object is a bridge to the platform-specific code.
  */
 expect object Awery {
+    /**
+     * Copies the given text to the clipboard.
+     *
+     * @param text The text to copy.
+     */
     fun copyToClipboard(text: String)
+    
+    /**
+     * Opens the given URL in the default browser of the device.
+     *
+     * @param url The URL to open.
+     */
     fun openUrl(url: String)
 
+    /**
+     * Shares the given text to the default sharing app of the device.
+     *
+     * @param text The text to share.
+     */
     fun share(text: String)
 
     /**

core/src/commonMain/kotlin/com/mrboomdev/awery/core/utils/CacheStorage.kt

@@ -6,12 +6,23 @@ import io.github.vinceglb.filekit.PlatformFile
 import io.github.vinceglb.filekit.absolutePath
 import io.github.vinceglb.filekit.readString
 import io.github.vinceglb.filekit.writeString
-import kotlinx.coroutines.runBlocking
 import kotlinx.serialization.KSerializer
 import kotlinx.serialization.json.Json
 import kotlinx.serialization.serializer
 import java.lang.System.currentTimeMillis
 
+/**
+ * Creates a new instance of [CacheStorage].
+ *
+ * @param directory The directory in which the cache files will be stored.
+ * @param maxSize The maximum size of the cache in bytes.
+ * @param strategy The strategy to use when storing and retrieving cache values.
+ * If not specified, defaults to [CacheStorage.Strategy.LRU].
+ * @param maxAge The maximum age of a cache value in milliseconds.
+ * If not specified, defaults to [Long.MAX_VALUE].
+ *
+ * @return A new instance of [CacheStorage].
+ */
 suspend inline fun <reified T> CacheStorage(
     directory: PlatformFile,
     maxSize: Long,

core/src/commonMain/kotlin/com/mrboomdev/awery/core/utils/CommonUtils.kt

@@ -1,10 +1,26 @@
 package com.mrboomdev.awery.core.utils
 
 import java.lang.AutoCloseable
+import kotlin.Boolean
+import kotlin.OptIn
+import kotlin.PublishedApi
+import kotlin.Suppress
+import kotlin.Throwable
+import kotlin.Unit
+import kotlin.addSuppressed
 import kotlin.contracts.ExperimentalContracts
 import kotlin.contracts.InvocationKind
 import kotlin.contracts.contract
 
+/**
+ * Closes the given [AutoCloseable] instance after executing the given [block].
+ * If [block] throws an exception, it will be re-thrown after closing the instance.
+ * If the instance cannot be closed because of an exception, the original exception will be re-thrown.
+ *
+ * @param block A lambda function that takes a [T] as an argument and returns a result of type [R].
+ * The function will be called with the instance of [T] as its argument and will be executed exactly once.
+ * @return The result of executing [block] with the instance of [T] as its argument.
+ */
 @OptIn(ExperimentalContracts::class)
 inline fun <T : AutoCloseable?, R> T.use(block: (T) -> R): R {
     contract {
@@ -22,6 +38,15 @@ inline fun <T : AutoCloseable?, R> T.use(block: (T) -> R): R {
     }
 }
 
+/**
+ * Closes this [AutoCloseable] instance, if it is not null.
+ * If the provided [cause] is not null, it will be re-thrown after closing the instance.
+ * If the instance cannot be closed because of an exception, the original exception will be re-thrown.
+ * If the instance can be closed successfully, the provided [cause] will be re-thrown.
+ *
+ * @param cause The exception to be re-thrown after closing the instance.
+ * @return Unit
+ */
 @PublishedApi
 internal fun AutoCloseable?.closeFinally(cause: Throwable?): Unit = when {
     this == null -> {}
@@ -34,14 +59,6 @@ internal fun AutoCloseable?.closeFinally(cause: Throwable?): Unit = when {
         }
 }
 
-inline fun <T> T.runIfNull(block: () -> Unit): T {
-    return apply {
-        if(this == null) {
-            block()
-        }
-    }
-}
-
 /**
  * Blocks the current thread until the provided [block] function returns `true`.
  *
@@ -53,6 +70,17 @@ inline fun await(block: () -> Boolean) {
     while(!block()) {}
 }
 
+/**
+ * Retries the provided [block] function until it returns a non-null result, or until an exception is thrown.
+ * If an exception is thrown, the provided [onFailure] function will be called with the exception as an argument.
+ * If [onFailure] is not provided, it defaults to an empty lambda function.
+ *
+ * @param onFailure A lambda function that takes a [Throwable] as an argument and returns [Unit].
+ *                  The function will be called with the exception as an argument if an exception is thrown by [block].
+ * @param block A lambda function that returns a result of type [T].
+ *                  The function will be repeatedly invoked until it returns a non-null result.
+ * @return The result of executing [block].
+ */
 inline fun <T> retryUntilSuccess(onFailure: (Throwable) -> Unit = {}, block: () -> T): T {
     var result: T? = null
 
@@ -67,6 +95,15 @@ inline fun <T> retryUntilSuccess(onFailure: (Throwable) -> Unit = {}, block: ()
     return result
 }
 
+/**
+ * Tries to execute the provided [computeValue] block and returns the result if it doesn't throw an exception.
+ * If the block throws an exception, the provided [fallbackComputeValue] block is executed with the exception as an argument
+ * and the result of that block is returned.
+ *
+ * @param computeValue A lambda function that returns a value of type [T].
+ * @param fallbackComputeValue A lambda function that takes a [Throwable] as an argument and returns a value of type [T].
+ * @return The result of executing [computeValue] or [fallbackComputeValue] depending on whether an exception was thrown.
+ */
 inline fun <T> tryOr(computeValue: () -> T, fallbackComputeValue: (Throwable) -> T): T {
     return try {
         computeValue()

core/src/commonMain/kotlin/com/mrboomdev/awery/core/utils/CoroutineUtils.kt

@@ -7,13 +7,10 @@ import kotlinx.coroutines.DelicateCoroutinesApi
 import kotlinx.coroutines.GlobalScope
 import kotlinx.coroutines.Job
 import kotlinx.coroutines.async
-import kotlinx.coroutines.delay
 import kotlinx.coroutines.launch
 import kotlinx.coroutines.supervisorScope
 import kotlin.coroutines.CoroutineContext
 import kotlin.coroutines.EmptyCoroutineContext
-import kotlin.time.Duration.Companion.milliseconds
-import kotlin.time.measureTimedValue
 
 /**
  * Launches a new coroutine in the [GlobalScope] without blocking the current thread and returns a reference to the coroutine as a [Job].
@@ -38,6 +35,20 @@ fun launchGlobal(
     return GlobalScope.launch(context, start, block)
 }
 
+/**
+ * Launches a new coroutine in the current scope and returns a reference to the coroutine as a [Job].
+ * The coroutine is cancelled when the resulting job is [cancelled][Job.cancel].
+ *
+ * If the coroutine throws an exception, it will be caught and passed to the [onCatch] function. The function will be called
+ *        with the exception as its argument.
+ *
+ * @param context additional to [CoroutineScope.coroutineContext] context of the coroutine.
+ * @param start coroutine start option. The default value is [CoroutineStart.DEFAULT].
+ * @param onCatch the function to call when the coroutine throws an exception. The function will be called
+ *        with the exception as its argument.
+ * @param block the coroutine code which will be invoked in the context of the provided scope.
+ * @return A [Job] representing the launched coroutine.
+ */
 fun CoroutineScope.launchTrying(
     context: CoroutineContext = EmptyCoroutineContext,
     start: CoroutineStart = CoroutineStart.DEFAULT,
@@ -49,6 +60,16 @@ fun CoroutineScope.launchTrying(
     block = block
 )
 
+/**
+ * Launches a new coroutine in the current scope that will be supervised by the [supervisorScope] function.
+ * This means that if the coroutine throws an exception, it will be propagated to the parent coroutine and
+ * will not cancel the parent coroutine.
+ *
+ * @param context additional to [CoroutineScope.coroutineContext] context of the coroutine.
+ * @param start coroutine start option. The default value is [CoroutineStart.DEFAULT].
+ * @param block the coroutine code which will be invoked in the context of the provided scope.
+ * @return A [Job] representing the launched coroutine.
+ */
 fun CoroutineScope.launchSupervise(
     context: CoroutineContext = EmptyCoroutineContext,
     start: CoroutineStart = CoroutineStart.DEFAULT,
@@ -58,7 +79,18 @@ fun CoroutineScope.launchSupervise(
 }
 
 /**
- * Useful for view models.
+ * A combination of [launchTrying] and [supervisorScope] that launches a coroutine in the current scope and
+ * returns its result as a [kotlinx.coroutines.Deferred] value. If the coroutine throws an exception, it will be caught and
+ * passed to the [onCatch] function.
+ *
+ * This function is useful for view models that need to handle exceptions in a centralized way.
+ *
+ * @param context additional to [CoroutineScope.coroutineContext] context of the coroutine.
+ * @param start coroutine start option. The default value is [CoroutineStart.DEFAULT].
+ * @param onCatch the function to call when the coroutine throws an exception. The function will be called
+ *        with the exception as its argument.
+ * @param block the coroutine code which will be invoked in the context of the provided scope.
+ * @return A [kotlinx.coroutines.Deferred] representing the launched coroutine.
  */
 fun CoroutineScope.launchTryingSupervise(
     context: CoroutineContext = EmptyCoroutineContext,
@@ -69,6 +101,20 @@ fun CoroutineScope.launchTryingSupervise(
     supervisorScope(block)
 }
 
+/**
+ * Launches a coroutine that will be cancelled when the resulting [kotlinx.coroutines.Deferred] is cancelled.
+ * The coroutine is launched in the current scope and returns its result as a [kotlinx.coroutines.Deferred] value.
+ * If the coroutine throws an exception, it will be caught and passed to the [onCatch] function.
+ *
+ * This function is useful for view models that need to handle exceptions in a centralized way.
+ *
+ * @param context additional to [CoroutineScope.coroutineContext] context of the coroutine.
+ * @param start coroutine start option. The default value is [CoroutineStart.DEFAULT].
+ * @param onCatch the function to call when the coroutine throws an exception. The function will be called
+ *        with the exception as its argument.
+ * @param block the coroutine code which will be invoked in the context of the provided scope.
+ * @return A [kotlinx.coroutines.Deferred] representing the launched coroutine.
+ */
 fun <T> CoroutineScope.asyncTrying(
     context: CoroutineContext = EmptyCoroutineContext,
     start: CoroutineStart = CoroutineStart.DEFAULT,
@@ -81,7 +127,18 @@ fun <T> CoroutineScope.asyncTrying(
 )
 
 /**
- * Useful for view models.
+ * A combination of [asyncTrying] and [supervisorScope] that launches a coroutine in the current scope and
+ * returns its result as a [kotlinx.coroutines.Deferred] value. If the coroutine throws an exception, it will be caught and
+ * passed to the [onCatch] function.
+ *
+ * This function is useful for view models that need to handle exceptions in a centralized way.
+ *
+ * @param context additional to [CoroutineScope.coroutineContext] context of the coroutine.
+ * @param start coroutine start option. The default value is [CoroutineStart.DEFAULT].
+ * @param onCatch the function to call when the coroutine throws an exception. The function will be called
+ *        with the exception as its argument.
+ * @param block the coroutine code which will be invoked in the context of the provided scope.
+ * @return A [kotlinx.coroutines.Deferred] representing the launched coroutine.
  */
 fun <T> CoroutineScope.asyncTryingSupervise(
     context: CoroutineContext = EmptyCoroutineContext,
@@ -90,17 +147,4 @@ fun <T> CoroutineScope.asyncTryingSupervise(
     block: suspend CoroutineScope.() -> T
 ) = asyncTrying(context, start, onCatch) {
     supervisorScope(block)
-}
-
-suspend inline fun <T> runForAtLeast(
-	block: () -> T,
-	durationInMillis: Long
-): T {
-	val (result, executionDuration) = measureTimedValue(block)
-	
-	if(executionDuration >= durationInMillis.milliseconds) {
-		delay(durationInMillis.milliseconds - executionDuration)
-	}
-	
-	return result
 }