Improve javadoc

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 <V, E> Result<V, E>.and(result: Result<V, E>): Result<V, E> {
 }
 
 /**
+ * Maps this [Result<V, E>][Result] to [Result<U, E>][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)
  *

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 <V, E> Result<V, E>.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 <V, E> Result<V, E>.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 <V, E> Result<V, E>.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 <V, E> Result<V, E>.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 <V, E> Result<V, E>.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].
  */

src/main/kotlin/com/github/michaelbull/result/Map.kt

@@ -1,8 +1,8 @@
 package com.github.michaelbull.result
 
 /**
- * Maps a [Result<V, E>][Result] to [Result<U, E>][Result] by applying a function to a contained
+ * Maps this [Result<V, E>][Result] to [Result<U, E>][Result] by either applying the [transform] function
- * [Ok] value, leaving an [Err] value untouched.
+ * 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 <V, E, U> Result<V, E>.map(transform: (V) -> U): Result<U, E> {
 }
 
 /**
- * Maps a [Result<V, E>][Result] to [Result<V, F>][Result] by applying a function to a contained
+ * Maps this [Result<V, E>][Result] to [Result<V, F>][Result] by either applying the [transform] function
- * [Err] value, leaving an [Ok] value untouched.
+ * 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 <V, E, F> Result<V, E>.mapError(transform: (E) -> F): Result<V,
 }
 
 /**
- * Map a [Result<V, E>][Result] to `U` by applying either the [success] function if the [Result]
+ * Maps this [Result<V, E>][Result] to `U` by applying either the [success] function if this [Result]
- * is [Ok] or the [failure] function if the [Result] is an [Err]. Both of these functions must
+ * 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 <V, E, U> Result<V, E>.mapBoth(
 
 // TODO: better name?
 /**
- * Map a [Result<V, E>][Result] to [Result<U, F>][Result] by applying either the [success] function
+ * Maps this [Result<V, E>][Result] to [Result<U, F>][Result] by applying either the [success] function
- * if the [Result] is [Ok] or the [failure] function if the [Result] is an [Err].
+ * 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)
  *

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 <V, E> Result<V, E>.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 <V, E> Result<V, E>.onFailure(callback: (E) -> Unit) = mapBoth({}, callback)

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 <V, E> Result<V, E>.or(result: Result<V, E>): Result<V, E> {
 }
 
 /**
+ * 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].

src/main/kotlin/com/github/michaelbull/result/Result.kt

@@ -24,5 +24,12 @@ sealed class Result<out V, out E> {
     }
 }
 
+/**
+ * Represents a successful [Result], containing a [value].
+ */
 data class Ok<out V> constructor(val value: V) : Result<V, Nothing>()
+
+/**
+ * Represents a failed [Result], containing an [error] value.
+ */
 data class Err<out E> constructor(val error: E) : Result<Nothing, E>()