From b2d29d62b7f86adf9c1a5ca8055b3e5aaa4e41e4 Mon Sep 17 00:00:00 2001 From: Michael Bull Date: Sun, 17 Dec 2017 00:14:27 +0000 Subject: [PATCH] Improve javadoc --- .../kotlin/com/github/michaelbull/result/And.kt | 5 +++++ .../kotlin/com/github/michaelbull/result/Get.kt | 14 ++++++++++++++ .../kotlin/com/github/michaelbull/result/Map.kt | 16 ++++++++-------- .../kotlin/com/github/michaelbull/result/On.kt | 4 ++-- .../kotlin/com/github/michaelbull/result/Or.kt | 5 +++++ .../com/github/michaelbull/result/Result.kt | 7 +++++++ 6 files changed, 41 insertions(+), 10 deletions(-) diff --git a/src/main/kotlin/com/github/michaelbull/result/And.kt b/src/main/kotlin/com/github/michaelbull/result/And.kt index 310592d..2fe5dfc 100644 --- a/src/main/kotlin/com/github/michaelbull/result/And.kt +++ b/src/main/kotlin/com/github/michaelbull/result/And.kt @@ -1,6 +1,8 @@ package com.github.michaelbull.result /** + * Returns [result] if this [Result] is [Ok], otherwise this [Err]. + * * - Rust: [Result.and](https://doc.rust-lang.org/std/result/enum.Result.html#method.and) * * @param result The [Result] to return if [Ok]. @@ -14,6 +16,9 @@ infix fun Result.and(result: Result): Result { } /** + * Maps this [Result][Result] to [Result][Result] by either applying the [transform] function + * if this [Result] is [Ok], or returning this [Err]. + * * - Elm: [Result.andThen](http://package.elm-lang.org/packages/elm-lang/core/latest/Result#andThen) * - Rust: [Result.and_then](https://doc.rust-lang.org/std/result/enum.Result.html#method.and_then) * diff --git a/src/main/kotlin/com/github/michaelbull/result/Get.kt b/src/main/kotlin/com/github/michaelbull/result/Get.kt index 5478cdf..ec76c96 100644 --- a/src/main/kotlin/com/github/michaelbull/result/Get.kt +++ b/src/main/kotlin/com/github/michaelbull/result/Get.kt @@ -1,6 +1,8 @@ package com.github.michaelbull.result /** + * Returns the [value][Ok.value] if this [Result] is [Ok], otherwise `null`. + * * - Elm: [Result.toMaybe](http://package.elm-lang.org/packages/elm-lang/core/latest/Result#toMaybe) * - Rust: [Result.ok](https://doc.rust-lang.org/std/result/enum.Result.html#method.ok) * @@ -14,6 +16,8 @@ fun Result.get(): V? { } /** + * Returns the [error][Err.error] if this [Result] is [Err], otherwise `null`. + * * - Rust: [Result.err](https://doc.rust-lang.org/std/result/enum.Result.html#method.err) * * @return The [error][Err.error] if [Err], otherwise `null`. @@ -26,6 +30,8 @@ fun Result.getError(): E? { } /** + * Returns the [value][Ok.value] if this [Result] is [Ok], otherwise [default]. + * * - Elm: [Result.withDefault](http://package.elm-lang.org/packages/elm-lang/core/latest/Result#withDefault) * - Haskell: [Result.fromLeft](https://hackage.haskell.org/package/base-4.10.0.0/docs/Data-Either.html#v:fromLeft) * - Rust: [Result.unwrap_or](https://doc.rust-lang.org/std/result/enum.Result.html#method.unwrap_or) @@ -41,6 +47,8 @@ infix fun Result.getOr(default: V): V { } /** + * Returns the [error][Err.error] if this [Result] is [Err], otherwise [default]. + * * - Haskell: [Result.fromRight](https://hackage.haskell.org/package/base-4.10.0.0/docs/Data-Either.html#v:fromRight) * * @param default The error to return if [Ok]. @@ -54,6 +62,9 @@ infix fun Result.getErrorOr(default: E): E { } /** + * Returns the [value][Ok.value] if this [Result] is [Ok], otherwise + * the [transformation][transform] of the [error][Err.error]. + * * - Elm: [Result.extract](http://package.elm-lang.org/packages/circuithub/elm-result-extra/1.4.0/Result-Extra#extract) * - Rust: [Result.unwrap_or_else](https://doc.rust-lang.org/src/core/result.rs.html#735-740) * @@ -68,6 +79,9 @@ infix inline fun Result.getOrElse(transform: (E) -> V): V { } /** + * Returns the [error][Err.error] if this [Result] is [Err], otherwise + * the [transformation][transform] of the [value][Ok.value]. + * * @param transform The transformation to apply to the [value][Ok.value]. * @return The [error][Err.error] if [Err], otherwise the [transformed][transform] [value][Ok.value]. */ diff --git a/src/main/kotlin/com/github/michaelbull/result/Map.kt b/src/main/kotlin/com/github/michaelbull/result/Map.kt index fd41253..7aa1720 100644 --- a/src/main/kotlin/com/github/michaelbull/result/Map.kt +++ b/src/main/kotlin/com/github/michaelbull/result/Map.kt @@ -1,8 +1,8 @@ package com.github.michaelbull.result /** - * Maps a [Result][Result] to [Result][Result] by applying a function to a contained - * [Ok] value, leaving an [Err] value untouched. + * Maps this [Result][Result] to [Result][Result] by either applying the [transform] function + * to the [value][Ok.value] if this [Result] is [Ok], or returning this [Err]. * * - Elm: [Result.map](http://package.elm-lang.org/packages/elm-lang/core/latest/Result#map) * - Haskell: [Data.Bifunctor.first](https://hackage.haskell.org/package/base-4.10.0.0/docs/Data-Bifunctor.html#v:first) @@ -19,8 +19,8 @@ infix inline fun Result.map(transform: (V) -> U): Result { } /** - * Maps a [Result][Result] to [Result][Result] by applying a function to a contained - * [Err] value, leaving an [Ok] value untouched. + * Maps this [Result][Result] to [Result][Result] by either applying the [transform] function + * to the [error][Err.error] if this [Result] is [Err], or returning this [Ok]. * * - Elm: [Result.mapError](http://package.elm-lang.org/packages/elm-lang/core/latest/Result#mapError) * - Haskell: [Data.Bifunctor.right](https://hackage.haskell.org/package/base-4.10.0.0/docs/Data-Bifunctor.html#v:second) @@ -37,8 +37,8 @@ infix inline fun Result.mapError(transform: (E) -> F): Result][Result] to `U` by applying either the [success] function if the [Result] - * is [Ok] or the [failure] function if the [Result] is an [Err]. Both of these functions must + * Maps this [Result][Result] to `U` by applying either the [success] function if this [Result] + * is [Ok], or the [failure] function if this [Result] is an [Err]. Both of these functions must * return the same type (`U`). * * - Elm: [Result.Extra.mapBoth](http://package.elm-lang.org/packages/circuithub/elm-result-extra/1.4.0/Result-Extra#mapBoth) @@ -60,8 +60,8 @@ inline fun Result.mapBoth( // TODO: better name? /** - * Map a [Result][Result] to [Result][Result] by applying either the [success] function - * if the [Result] is [Ok] or the [failure] function if the [Result] is an [Err]. + * Maps this [Result][Result] to [Result][Result] by applying either the [success] function + * if this [Result] is [Ok], or the [failure] function if this [Result] is an [Err]. * * - Haskell: [Data.Bifunctor.Bimap](https://hackage.haskell.org/package/base-4.10.0.0/docs/Data-Bifunctor.html#v:bimap) * diff --git a/src/main/kotlin/com/github/michaelbull/result/On.kt b/src/main/kotlin/com/github/michaelbull/result/On.kt index d3376f6..4dbe32c 100644 --- a/src/main/kotlin/com/github/michaelbull/result/On.kt +++ b/src/main/kotlin/com/github/michaelbull/result/On.kt @@ -1,13 +1,13 @@ package com.github.michaelbull.result /** - * Calls a [callback] if the [Result] is [Ok]. + * Invokes a [callback] if this [Result] is [Ok]. * @param callback The function to call. */ infix inline fun Result.onSuccess(callback: (V) -> Unit) = mapBoth(callback, {}) /** - * Calls a [callback] if the [Result] is [Err]. + * Invokes a [callback] if this [Result] is [Err]. * @param callback The function to call. */ infix inline fun Result.onFailure(callback: (E) -> Unit) = mapBoth({}, callback) diff --git a/src/main/kotlin/com/github/michaelbull/result/Or.kt b/src/main/kotlin/com/github/michaelbull/result/Or.kt index 3fbd0bb..0661139 100644 --- a/src/main/kotlin/com/github/michaelbull/result/Or.kt +++ b/src/main/kotlin/com/github/michaelbull/result/Or.kt @@ -1,6 +1,8 @@ package com.github.michaelbull.result /** + * Returns [result] if this [Result] is [Err], otherwise this [Ok]. + * * - Rust: [Result.or](https://doc.rust-lang.org/std/result/enum.Result.html#method.or) * * @param result The [Result] to return if [Err]. @@ -14,6 +16,9 @@ infix fun Result.or(result: Result): Result { } /** + * Returns the [transformation][transform] of the [error][Err.error] if this [Result] is [Err], + * otherwise this [Ok]. + * * - Rust: [Result.or_else](https://doc.rust-lang.org/std/result/enum.Result.html#method.or_else) * * @param transform The transformation to apply to the [error][Err.error]. diff --git a/src/main/kotlin/com/github/michaelbull/result/Result.kt b/src/main/kotlin/com/github/michaelbull/result/Result.kt index 9e8a9c5..ee94549 100644 --- a/src/main/kotlin/com/github/michaelbull/result/Result.kt +++ b/src/main/kotlin/com/github/michaelbull/result/Result.kt @@ -24,5 +24,12 @@ sealed class Result { } } +/** + * Represents a successful [Result], containing a [value]. + */ data class Ok constructor(val value: V) : Result() + +/** + * Represents a failed [Result], containing an [error] value. + */ data class Err constructor(val error: E) : Result()