From 14aa9ca26c3903344f0b38271cac0488270cf541 Mon Sep 17 00:00:00 2001
From: InsanusMokrassar <ovsyannikov.alexey95@gmail.com>
Date: Tue, 22 Dec 2020 15:21:25 +0600
Subject: [PATCH] update documentation

---
 .../micro_utils/coroutines/HandleSafely.kt    | 25 +++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/coroutines/src/commonMain/kotlin/dev/inmo/micro_utils/coroutines/HandleSafely.kt b/coroutines/src/commonMain/kotlin/dev/inmo/micro_utils/coroutines/HandleSafely.kt
index 91daf1de16c..327a902cdcf 100644
--- a/coroutines/src/commonMain/kotlin/dev/inmo/micro_utils/coroutines/HandleSafely.kt
+++ b/coroutines/src/commonMain/kotlin/dev/inmo/micro_utils/coroutines/HandleSafely.kt
@@ -12,8 +12,25 @@ typealias ExceptionHandler<T> = suspend (Throwable) -> T
  */
 var defaultSafelyExceptionHandler: ExceptionHandler<Nothing> = { throw it }
 
+/**
+ * Key for [SafelyExceptionHandler] which can be used in [CoroutineContext.get] to get current default
+ * [SafelyExceptionHandler]
+ */
 class SafelyExceptionHandlerKey<T> : CoroutineContext.Key<SafelyExceptionHandler<T>>
+
+/**
+ * Shortcut for creating instance of [SafelyExceptionHandlerKey]
+ */
+@Suppress("NOTHING_TO_INLINE")
 inline fun <T> safelyExceptionHandlerKey() = SafelyExceptionHandlerKey<T>()
+
+/**
+ * Wrapper for [ExceptionHandler] which can be used in [CoroutineContext] to set local (for [CoroutineContext]) default
+ * [ExceptionHandler]. To get it use [CoroutineContext.get] with key [SafelyExceptionHandlerKey]
+ *
+ * @see SafelyExceptionHandlerKey
+ * @see ExceptionHandler
+ */
 class SafelyExceptionHandler<T>(
     val handler: ExceptionHandler<T>
 ) : CoroutineContext.Element {
@@ -24,11 +41,19 @@ class SafelyExceptionHandler<T>(
 /**
  * It will run [block] inside of [supervisorScope] to avoid problems with catching of exceptions
  *
+ * Priorities of [ExceptionHandler]s:
+ *
+ * * [onException] In case if custom (will be used anyway if not [defaultSafelyExceptionHandler])
+ * * [CoroutineContext.get] with [SafelyExceptionHandlerKey] as key
+ * * [defaultSafelyExceptionHandler]
+ *
  * @param [onException] Will be called when happen exception inside of [block]. By default will throw exception - this
  * exception will be available for catching
  *
  * @see defaultSafelyExceptionHandler
  * @see safelyWithoutExceptions
+ * @see SafelyExceptionHandlerKey
+ * @see SafelyExceptionHandler
  */
 suspend inline fun <T> safely(
     noinline onException: ExceptionHandler<T> = defaultSafelyExceptionHandler,