From edfd9333489d4d8f88752564295dcf2e84b5d919 Mon Sep 17 00:00:00 2001 From: Ilya Gorbunov Date: Sat, 30 Nov 2019 07:33:43 +0300 Subject: [PATCH] Improve Result docs to emphasize that any Throwable exception is caught #KT-33447 Fixed --- libraries/stdlib/src/kotlin/util/Result.kt | 64 +++++++++++----------- 1 file changed, 32 insertions(+), 32 deletions(-) diff --git a/libraries/stdlib/src/kotlin/util/Result.kt b/libraries/stdlib/src/kotlin/util/Result.kt index c292511b020..28beacd0763 100644 --- a/libraries/stdlib/src/kotlin/util/Result.kt +++ b/libraries/stdlib/src/kotlin/util/Result.kt @@ -12,7 +12,7 @@ import kotlin.internal.InlineOnly import kotlin.jvm.JvmField /** - * A discriminated union that encapsulates successful outcome with a value of type [T] + * A discriminated union that encapsulates a successful outcome with a value of type [T] * or a failure with an arbitrary [Throwable] exception. */ @Suppress("NON_PUBLIC_PRIMARY_CONSTRUCTOR_OF_INLINE_CLASS") @@ -24,13 +24,13 @@ public inline class Result @PublishedApi internal constructor( // discovery /** - * Returns `true` if this instance represents successful outcome. + * Returns `true` if this instance represents a successful outcome. * In this case [isFailure] returns `false`. */ public val isSuccess: Boolean get() = value !is Failure /** - * Returns `true` if this instance represents failed outcome. + * Returns `true` if this instance represents a failed outcome. * In this case [isSuccess] returns `false`. */ public val isFailure: Boolean get() = value is Failure @@ -41,7 +41,7 @@ public inline class Result @PublishedApi internal constructor( * Returns the encapsulated value if this instance represents [success][Result.isSuccess] or `null` * if it is [failure][Result.isFailure]. * - * This function is shorthand for `getOrElse { null }` (see [getOrElse]) or + * This function is a shorthand for `getOrElse { null }` (see [getOrElse]) or * `fold(onSuccess = { it }, onFailure = { null })` (see [fold]). */ @InlineOnly @@ -52,10 +52,10 @@ public inline class Result @PublishedApi internal constructor( } /** - * Returns the encapsulated exception if this instance represents [failure][isFailure] or `null` + * Returns the encapsulated [Throwable] exception if this instance represents [failure][isFailure] or `null` * if it is [success][isSuccess]. * - * This function is shorthand for `fold(onSuccess = { null }, onFailure = { it })` (see [fold]). + * This function is a shorthand for `fold(onSuccess = { null }, onFailure = { it })` (see [fold]). */ public fun exceptionOrNull(): Throwable? = when (value) { @@ -89,7 +89,7 @@ public inline class Result @PublishedApi internal constructor( Result(value) /** - * Returns an instance that encapsulates the given [exception] as failure. + * Returns an instance that encapsulates the given [Throwable] [exception] as failure. */ @InlineOnly public inline fun failure(exception: Throwable): Result = @@ -128,7 +128,7 @@ internal fun Result<*>.throwOnFailure() { /** * Calls the specified function [block] and returns its encapsulated result if invocation was successful, - * catching and encapsulating any thrown exception as a failure. + * catching any [Throwable] exception that was thrown from the [block] function execution and encapsulating it as a failure. */ @InlineOnly @SinceKotlin("1.3") @@ -141,8 +141,8 @@ public inline fun runCatching(block: () -> R): Result { } /** - * Calls the specified function [block] with `this` value as its receiver and returns its encapsulated result - * if invocation was successful, catching and encapsulating any thrown exception as a failure. + * Calls the specified function [block] with `this` value as its receiver and returns its encapsulated result if invocation was successful, + * catching any [Throwable] exception that was thrown from the [block] function execution and encapsulating it as a failure. */ @InlineOnly @SinceKotlin("1.3") @@ -157,10 +157,10 @@ public inline fun T.runCatching(block: T.() -> R): Result { // -- extensions --- /** - * Returns the encapsulated value if this instance represents [success][Result.isSuccess] or throws the encapsulated exception + * Returns the encapsulated value if this instance represents [success][Result.isSuccess] or throws the encapsulated [Throwable] exception * if it is [failure][Result.isFailure]. * - * This function is shorthand for `getOrElse { throw it }` (see [getOrElse]). + * This function is a shorthand for `getOrElse { throw it }` (see [getOrElse]). */ @InlineOnly @SinceKotlin("1.3") @@ -171,11 +171,11 @@ public inline fun Result.getOrThrow(): T { /** * Returns the encapsulated value if this instance represents [success][Result.isSuccess] or the - * result of [onFailure] function for encapsulated exception if it is [failure][Result.isFailure]. + * result of [onFailure] function for the encapsulated [Throwable] exception if it is [failure][Result.isFailure]. * - * Note, that an exception thrown by [onFailure] function is rethrown by this function. + * Note, that this function rethrows any [Throwable] exception thrown by [onFailure] function. * - * This function is shorthand for `fold(onSuccess = { it }, onFailure = onFailure)` (see [fold]). + * This function is a shorthand for `fold(onSuccess = { it }, onFailure = onFailure)` (see [fold]). */ @InlineOnly @SinceKotlin("1.3") @@ -193,7 +193,7 @@ public inline fun Result.getOrElse(onFailure: (exception: Throwabl * Returns the encapsulated value if this instance represents [success][Result.isSuccess] or the * [defaultValue] if it is [failure][Result.isFailure]. * - * This function is shorthand for `getOrElse { defaultValue }` (see [getOrElse]). + * This function is a shorthand for `getOrElse { defaultValue }` (see [getOrElse]). */ @InlineOnly @SinceKotlin("1.3") @@ -203,10 +203,10 @@ public inline fun Result.getOrDefault(defaultValue: R): R { } /** - * Returns the the result of [onSuccess] for encapsulated value if this instance represents [success][Result.isSuccess] - * or the result of [onFailure] function for encapsulated exception if it is [failure][Result.isFailure]. + * Returns the result of [onSuccess] for the encapsulated value if this instance represents [success][Result.isSuccess] + * or the result of [onFailure] function for the encapsulated [Throwable] exception if it is [failure][Result.isFailure]. * - * Note, that an exception thrown by [onSuccess] or by [onFailure] function is rethrown by this function. + * Note, that this function rethrows any [Throwable] exception thrown by [onSuccess] or by [onFailure] function. */ @InlineOnly @SinceKotlin("1.3") @@ -227,11 +227,11 @@ public inline fun Result.fold( // transformation /** - * Returns the encapsulated result of the given [transform] function applied to encapsulated value + * Returns the encapsulated result of the given [transform] function applied to the encapsulated value * if this instance represents [success][Result.isSuccess] or the - * original encapsulated exception if it is [failure][Result.isFailure]. + * original encapsulated [Throwable] exception if it is [failure][Result.isFailure]. * - * Note, that an exception thrown by [transform] function is rethrown by this function. + * Note, that this function rethrows any [Throwable] exception thrown by [transform] function. * See [mapCatching] for an alternative that encapsulates exceptions. */ @InlineOnly @@ -247,12 +247,12 @@ public inline fun Result.map(transform: (value: T) -> R): Result { } /** - * Returns the encapsulated result of the given [transform] function applied to encapsulated value + * Returns the encapsulated result of the given [transform] function applied to the encapsulated value * if this instance represents [success][Result.isSuccess] or the - * original encapsulated exception if it is [failure][Result.isFailure]. + * original encapsulated [Throwable] exception if it is [failure][Result.isFailure]. * - * Any exception thrown by [transform] function is caught, encapsulated as a failure and returned by this function. - * See [map] for an alternative that rethrows exceptions. + * This function catches any [Throwable] exception thrown by [transform] function and encapsulates it as a failure. + * See [map] for an alternative that rethrows exceptions from `transform` function. */ @InlineOnly @SinceKotlin("1.3") @@ -264,11 +264,11 @@ public inline fun Result.mapCatching(transform: (value: T) -> R): Resu } /** - * Returns the encapsulated result of the given [transform] function applied to encapsulated exception + * Returns the encapsulated result of the given [transform] function applied to the encapsulated [Throwable] exception * if this instance represents [failure][Result.isFailure] or the * original encapsulated value if it is [success][Result.isSuccess]. * - * Note, that an exception thrown by [transform] function is rethrown by this function. + * Note, that this function rethrows any [Throwable] exception thrown by [transform] function. * See [recoverCatching] for an alternative that encapsulates exceptions. */ @InlineOnly @@ -284,11 +284,11 @@ public inline fun Result.recover(transform: (exception: Throwable) } /** - * Returns the encapsulated result of the given [transform] function applied to encapsulated exception + * Returns the encapsulated result of the given [transform] function applied to the encapsulated [Throwable] exception * if this instance represents [failure][Result.isFailure] or the * original encapsulated value if it is [success][Result.isSuccess]. * - * Any exception thrown by [transform] function is caught, encapsulated as a failure and returned by this function. + * This function catches any [Throwable] exception thrown by [transform] function and encapsulates it as a failure. * See [recover] for an alternative that rethrows exceptions. */ @InlineOnly @@ -304,7 +304,7 @@ public inline fun Result.recoverCatching(transform: (exception: Th // "peek" onto value/exception and pipe /** - * Performs the given [action] on encapsulated exception if this instance represents [failure][Result.isFailure]. + * Performs the given [action] on the encapsulated [Throwable] exception if this instance represents [failure][Result.isFailure]. * Returns the original `Result` unchanged. */ @InlineOnly @@ -318,7 +318,7 @@ public inline fun Result.onFailure(action: (exception: Throwable) -> Unit } /** - * Performs the given [action] on encapsulated value if this instance represents [success][Result.isSuccess]. + * Performs the given [action] on the encapsulated value if this instance represents [success][Result.isSuccess]. * Returns the original `Result` unchanged. */ @InlineOnly