Add inline documentation to library methods

build.gradle

@@ -37,14 +37,14 @@ compileTestKotlin {
 }
 
 dokka {
-    outputFormat = 'javadoc'
+    outputFormat = 'html'
     outputDirectory = "$buildDir/docs"
 }
 
-task javadocJar(type: Jar, dependsOn: dokka) {
+task kdocJar(type: Jar, dependsOn: dokka) {
     group = LifecycleBasePlugin.BUILD_GROUP
-    description = 'Assembles a jar archive containing the Javadoc API documentation.'
+    description = 'Assembles a jar archive containing the KDoc API documentation.'
-    classifier = 'javadoc'
+    classifier = 'kdoc'
     from dokka.outputDirectory
 }
 
@@ -59,7 +59,7 @@ publishing {
     publications {
         mavenJava(MavenPublication) {
             from components.java
-            artifact javadocJar
+            artifact kdocJar
             artifact sourcesJar
         }
     }

src/main/kotlin/com/mikebull94/result/And.kt

@@ -1,7 +1,10 @@
 package com.mikebull94.result
 
 /**
- * Rust: [Result.and](https://doc.rust-lang.org/std/result/enum.Result.html#method.and)
+ * - Rust: [Result.and](https://doc.rust-lang.org/std/result/enum.Result.html#method.and)
+ *
+ * @param result The [Result] to return if [Ok].
+ * @return The [result] if [Ok], otherwise [err].
  */
 infix fun <V, E> Result<V, E>.and(result: Result<V, E>): Result<V, E> {
     return when (this) {
@@ -13,6 +16,9 @@ infix fun <V, E> Result<V, E>.and(result: Result<V, E>): Result<V, E> {
 /**
  * - 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)
+ *
+ * @param transform The transformation to apply to the [value][Ok.value].
+ * @return The [transformed][transform] [Result] if [Ok], otherwise [err].
  */
 infix inline fun <V, E, U> Result<V, E>.andThen(transform: (V) -> Result<U, E>): Result<U, E> {
     return when (this) {

src/main/kotlin/com/mikebull94/result/Get.kt

@@ -3,6 +3,8 @@ package com.mikebull94.result
 /**
  * - 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)
+ *
+ * @return The [value][Ok.value] if [Ok], otherwise `null`.
  */
 fun <V, E> Result<V, E>.get(): V? {
     return when (this) {
@@ -13,6 +15,8 @@ fun <V, E> Result<V, E>.get(): V? {
 
 /**
  * - Rust: [Result.err](https://doc.rust-lang.org/std/result/enum.Result.html#method.err)
+ *
+ * @return The [error][Error.error] if [Error], otherwise `null`.
  */
 fun <V, E> Result<V, E>.getError(): E? {
     return when (this) {
@@ -25,6 +29,9 @@ fun <V, E> Result<V, E>.getError(): E? {
  * - 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)
+ *
+ * @param default The value to return if [Error].
+ * @return The [value][Ok.value] if [Ok], otherwise [default].
  */
 infix fun <V, E> Result<V, E>.getOr(default: V): V {
     return when (this) {
@@ -35,6 +42,9 @@ infix fun <V, E> Result<V, E>.getOr(default: V): V {
 
 /**
  * - 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].
+ * @return The [error][Error.error] if [Error], otherwise [default].
  */
 infix fun <V, E> Result<V, E>.getErrorOr(default: E): E {
     return when (this) {
@@ -46,6 +56,9 @@ infix fun <V, E> Result<V, E>.getErrorOr(default: E): E {
 /**
  * - 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)
+ *
+ * @param transform The transformation to apply to the [error][Error.error].
+ * @return The [value][Ok.value] if [Ok], otherwise the [transformed][transform] [error][Error.error].
  */
 infix inline fun <V, E> Result<V, E>.getOrElse(transform: (E) -> V): V {
     return when (this) {

src/main/kotlin/com/mikebull94/result/Iterable.kt

@@ -1,5 +1,12 @@
 package com.mikebull94.result
 
+/**
+ * Accumulates value starting with [initial] value and applying [operation] from left to right to
+ * current accumulator value and each element.
+ *
+ * @param initial The value to start with.
+ * @param operation The operation to apply to each element and current accumulator value.
+ */
 inline fun <T, R, E> Iterable<T>.fold(
     initial: R,
     operation: (acc: R, T) -> Result<R, E>
@@ -20,6 +27,13 @@ inline fun <T, R, E> Iterable<T>.fold(
     return ok(accumulator)
 }
 
+/**
+ * Accumulates value starting with [initial] value and applying [operation] from right to left to
+ * each element and current accumulator value.
+ *
+ * @param initial The value to start with.
+ * @param operation The operation to apply to each element and current accumulator value.
+ */
 inline fun <T, R, E> List<T>.foldRight(
     initial: R,
     operation: (T, acc: R) -> Result<R, E>
@@ -44,12 +58,21 @@ inline fun <T, R, E> List<T>.foldRight(
 }
 
 /**
+ * Combine a vararg of [Results][Result] into a single [Result] (holding a [List]).
+ *
  * - Elm: [Result.Extra.combine](http://package.elm-lang.org/packages/circuithub/elm-result-extra/1.4.0/Result-Extra#combine)
+ *
+ * @param results The [Results][Result] to combine.
+ * @return The combined [Result].
  */
 fun <V, E> combine(vararg results: Result<V, E>) = results.asIterable().combine()
 
 /**
+ * Combine an [Iterable] of [Results][Result] into a single [Result] (holding a [List]).
+ *
  * - Elm: [Result.Extra.combine](http://package.elm-lang.org/packages/circuithub/elm-result-extra/1.4.0/Result-Extra#combine)
+ *
+ * @return The combined [Result].
  */
 fun <V, E> Iterable<Result<V, E>>.combine(): Result<List<V>, E> {
     return ok(map {
@@ -61,36 +84,73 @@ fun <V, E> Iterable<Result<V, E>>.combine(): Result<List<V>, E> {
 }
 
 /**
+ * Extracts from a vararg of [Results][Result] all the [Ok] elements. All the [Ok] elements are
+ * extracted in order.
+ *
  * - Haskell: [Data.Either.lefts](https://hackage.haskell.org/package/base-4.10.0.0/docs/Data-Either.html#v:lefts)
+ *
+ * @param results The [Results][Result] from which to extract [Ok] elements.
+ * @return The extracted [Ok] elements.
  */
 fun <V, E> getAll(vararg results: Result<V, E>) = results.asIterable().getAll()
 
 /**
+ * Extracts from an [Iterable] of [Results][Result] all the [Ok] elements. All the [Ok] elements
+ * are extracted in order.
+ *
  * - Haskell: [Data.Either.lefts](https://hackage.haskell.org/package/base-4.10.0.0/docs/Data-Either.html#v:lefts)
+ *
+ * @return The extracted [Ok] elements.
  */
 fun <V, E> Iterable<Result<V, E>>.getAll(): List<V> {
     return filter { it is Ok }.map { (it as Ok).value }
 }
 
 /**
+ * Extracts from a vararg of [Results][Result] all the [Error] elements. All the [Error] elements
+ * are extracted in order.
+ *
  * - Haskell: [Data.Either.rights](https://hackage.haskell.org/package/base-4.10.0.0/docs/Data-Either.html#v:rights)
+ *
+ * @param results The [Results][Result] from which to extract [Error] elements.
+ * @return The extracted [Error] elements.
  */
 fun <V, E> getAllErrors(vararg results: Result<V, E>) = results.asIterable().getAllErrors()
 
 /**
+ * Extracts from an [Iterable] of [Results][Result] all the [Error] elements. All the [Error]
+ * elements are extracted in order.
+ *
  * - Haskell: [Data.Either.rights](https://hackage.haskell.org/package/base-4.10.0.0/docs/Data-Either.html#v:rights)
+ *
+ * @return The extracted [Error] elements.
  */
 fun <V, E> Iterable<Result<V, E>>.getAllErrors(): List<E> {
     return filter { it is Error }.map { (it as Error).error }
 }
 
 /**
+ * Partitions a vararg of [Results][Result] into a [Pair] of [Lists][List]. All the [Ok] elements
+ * are extracted, in order, to the [first][Pair.first] value. Similarly the [Error] elements are
+ * extracted to the [Pair.second] value.
+ *
  * - Haskell: [Data.Either.partitionEithers](https://hackage.haskell.org/package/base-4.10.0.0/docs/Data-Either.html#v:partitionEithers)
+ *
+ * @param results The [Results][Result] to partition.
+ * @return A [Pair] of [Lists][List] where the [first][Pair.first] value
+ * contains the [Ok] elements and the [second][Pair.second] value contains the [Error] elements.
  */
 fun <V, E> partition(vararg results: Result<V, E>) = results.asIterable().partition()
 
 /**
+ * Partitions an [Iterable] of [Results][Result] into a [Pair] of  [Lists][List]. All the [Ok]
+ * elements are extracted, in order, to the [first][Pair.first] value. Similarly the [Error]
+ * elements are extracted to the [Pair.second] value.
+ *
  * - Haskell: [Data.Either.partitionEithers](https://hackage.haskell.org/package/base-4.10.0.0/docs/Data-Either.html#v:partitionEithers)
+ *
+ * @return A [Pair] of [Lists][List] where the [first][Pair.first] value
+ * contains the [Ok] elements and the [second][Pair.second] value contains the [Error] elements.
  */
 fun <V, E> Iterable<Result<V, E>>.partition(): Pair<List<V>, List<E>> {
     val values = mutableListOf<V>()

src/main/kotlin/com/mikebull94/result/Map.kt

@@ -1,9 +1,15 @@
 package com.mikebull94.result
 
 /**
+ * Maps a [Result<V, E>][Result] to [Result<U, E>][Result] by applying a function to a contained
+ * [Ok] value, leaving an [Error] value untouched.
+ *
  * - 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)
  * - Rust: [Result.map](https://doc.rust-lang.org/std/result/enum.Result.html#method.map)
+ *
+ * @param transform The transformation to apply to the [value][Ok.value]
+ * @return The [transformed][transform] [Result] if [Ok], otherwise [err].
  */
 infix inline fun <V, E, U> Result<V, E>.map(transform: (V) -> U): Result<U, E> {
     return when (this) {
@@ -13,9 +19,15 @@ 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
+ * [Error] value, leaving an [Ok] value untouched.
+ *
  * - 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)
  * - Rust: [Result.map_err](https://doc.rust-lang.org/std/result/enum.Result.html#method.map_err)
+ *
+ * @param transform The transformation to apply to the [error][Error.error].
+ * @return The [value][Ok.value] if [Ok], otherwise the [transformed][transform] [Error].
  */
 infix inline fun <V, E, F> Result<V, E>.mapError(transform: (E) -> F): Result<V, F> {
     return when (this) {
@@ -25,8 +37,16 @@ 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]
+ * is [Ok] or the [failure] function if the [Result] is an [Error]. 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)
  * - Haskell: [Data.Either.either](https://hackage.haskell.org/package/base-4.10.0.0/docs/Data-Either.html#v:either)
+ *
+ * @param success The function to apply to `V` if [Ok].
+ * @param failure The function to apply to `E` if [Error].
+ * @return The mapped value.
  */
 inline fun <V, E, U> Result<V, E>.mapBoth(
     success: (V) -> U,
@@ -40,12 +60,19 @@ 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
+ * if the [Result] is [Ok] or the [failure] function if the [Result] is an [Error].
+ *
  * - Haskell: [Data.Bifunctor.Bimap](https://hackage.haskell.org/package/base-4.10.0.0/docs/Data-Bifunctor.html#v:bimap)
+ *
+ * @param success The function to apply to `V` if [Ok].
+ * @param failure The function to apply to `E` if [Error].
+ * @return The mapped [Result].
  */
-inline fun <V1, V2, E1, E2> Result<V1, E1>.mapEither(
+inline fun <V, E, U, F> Result<V, E>.mapEither(
-    success: (V1) -> V2,
+    success: (V) -> U,
-    failure: (E1) -> E2
+    failure: (E) -> F
-): Result<V2, E2> {
+): Result<U, F> {
     return when (this) {
         is Ok -> ok(success(value))
         is Error -> err(failure(error))

src/main/kotlin/com/mikebull94/result/On.kt

@@ -1,4 +1,13 @@
 package com.mikebull94.result
 
+/**
+ * Calls a [callback] if the [Result] is [Ok].
+ * @param callback The function to call.
+ */
 fun <V, E> Result<V, E>.onSuccess(callback: (V) -> Unit) = mapBoth(callback, {})
+
+/**
+ * Calls a [callback] if the [Result] is [Error].
+ * @param callback The function to call.
+ */
 fun <V, E> Result<V, E>.onFailure(callback: (E) -> Unit) = mapBoth({}, callback)

src/main/kotlin/com/mikebull94/result/Or.kt

@@ -2,6 +2,9 @@ package com.mikebull94.result
 
 /**
  * - Rust: [Result.or](https://doc.rust-lang.org/std/result/enum.Result.html#method.or)
+ *
+ * @param result The [Result] to return if [Error].
+ * @return The [result] if [Error], otherwise [ok].
  */
 infix fun <V, E> Result<V, E>.or(result: Result<V, E>): Result<V, E> {
     return when (this) {
@@ -12,6 +15,9 @@ infix fun <V, E> Result<V, E>.or(result: Result<V, E>): Result<V, E> {
 
 /**
  * - 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][Error.error].
+ * @return The [transformed][transform] [Result] if [Error], otherwise [ok].
  */
 infix inline fun <V, E> Result<V, E>.orElse(transform: (E) -> Result<V, E>): Result<V, E> {
     return when (this) {

src/main/kotlin/com/mikebull94/result/Result.kt

@@ -1,6 +1,8 @@
 package com.mikebull94.result
 
 /**
+ * [Result] is a type that represents either success ([Ok]) or failure ([Error]).
+ *
  * - Elm: [Result](http://package.elm-lang.org/packages/elm-lang/core/5.1.1/Result)
  * - Haskell: [Data.Either](https://hackage.haskell.org/package/base-4.10.0.0/docs/Data-Either.html)
  * - Rust: [Result](https://doc.rust-lang.org/std/result/enum.Result.html)

src/main/kotlin/com/mikebull94/result/ResultIterator.kt

@@ -1,22 +1,39 @@
 package com.mikebull94.result
 
 /**
+ * Creates an [Iterator] over the possibly contained [value][Ok.value].
+ * The iterator yields one [value][Ok.value] if the [Result] is [Ok], otherwise throws [NoSuchElementException].
+ *
  * - Rust: [Result.iter](https://doc.rust-lang.org/std/result/enum.Result.html#method.iter)
+ *
+ * @return [Iterator] over the possibly contained [value][Ok.value].
  */
 fun <V, E> Result<V, E>.iterator(): Iterator<V> {
     return ResultIterator(this)
 }
 
 /**
- * Rust: [Result.iter_mut](https://doc.rust-lang.org/std/result/enum.Result.html#method.iter_mut)
+ * Creates a [MutableIterator] over the possibly contained [value][Ok.value].
+ * The iterator yields one [value][Ok.value] if the [Result] is [Ok], otherwise throws [NoSuchElementException].
+ *
+ * - Rust: [Result.iter_mut](https://doc.rust-lang.org/std/result/enum.Result.html#method.iter_mut)
+ *
+ * @return The [MutableIterator] over the possibly contained [value][Ok.value].
  */
 fun <V, E> Result<V, E>.mutableIterator(): MutableIterator<V> {
     return ResultIterator(this)
 }
 
 private class ResultIterator<out V, out E>(private val result: Result<V, E>) : MutableIterator<V> {
+
+    /**
+     * A flag indicating whether this [Iterator] has [yielded] its [Result].
+     */
     private var yielded = false
 
+    /**
+     * @return `true` if the [value][Ok.value] is not [yielded] and [Ok], `false` otherwise.
+     */
     override fun hasNext(): Boolean {
         if (yielded) {
             return false
@@ -28,6 +45,10 @@ private class ResultIterator<out V, out E>(private val result: Result<V, E>) : M
         }
     }
 
+    /**
+     * @return The [Result's][Result] [value][Ok.value] if not [yielded] and [Ok].
+     * @throws NoSuchElementException if the [Result] is [yielded] or is not [Ok].
+     */
     override fun next(): V {
         if (!yielded && result is Ok) {
             yielded = true
@@ -37,6 +58,9 @@ private class ResultIterator<out V, out E>(private val result: Result<V, E>) : M
         }
     }
 
+    /**
+     * Flags this [Iterator] as having [yielded] its [Result].
+     */
     override fun remove() {
         yielded = true
     }

src/main/kotlin/com/mikebull94/result/Unwrap.kt

@@ -3,7 +3,11 @@ package com.mikebull94.result
 class UnwrapException(message: String) : Exception(message)
 
 /**
+ * Unwraps a [Result], yielding the [value][Ok.value].
+ *
  * - Rust: [Result.unwrap](https://doc.rust-lang.org/std/result/enum.Result.html#method.unwrap)
+ *
+ * @throws UnwrapException if the [Result] is an [Error], with a message containing the [error][Error.error].
  */
 fun <V, E> Result<V, E>.unwrap(): V {
     return when (this) {
@@ -13,7 +17,12 @@ fun <V, E> Result<V, E>.unwrap(): V {
 }
 
 /**
+ * Unwraps a [Result], yielding the [value][Ok.value].
+ *
  * - Rust: [Result.expect](https://doc.rust-lang.org/std/result/enum.Result.html#method.expect)
+ *
+ * @param message The message to include in the [UnwrapException] if the [Result] is an [Error].
+ * @throws UnwrapException if the [Result] is an [Error], with the specified [message].
  */
 infix fun <V, E> Result<V, E>.expect(message: String): V {
     return when (this) {
@@ -23,7 +32,11 @@ infix fun <V, E> Result<V, E>.expect(message: String): V {
 }
 
 /**
+ * Unwraps a [Result], yielding the [error][Error.error].
+ *
  * - Rust: [Result.unwrap_err](https://doc.rust-lang.org/std/result/enum.Result.html#method.unwrap_err)
+ *
+ * @throws UnwrapException if the [Result] is [Ok], with a message containing the [value][Ok.value].
  */
 fun <V, E> Result<V, E>.unwrapError(): E {
     return when (this) {
@@ -33,7 +46,12 @@ fun <V, E> Result<V, E>.unwrapError(): E {
 }
 
 /**
- * - Rust: [Reseult.expect_err](https://doc.rust-lang.org/std/result/enum.Result.html#method.expect_err)
+ * Unwraps a [Result], yielding the [error][Error.error].
+ *
+ * - Rust: [Result.expect_err](https://doc.rust-lang.org/std/result/enum.Result.html#method.expect_err)
+ *
+ * @param message The message to include in the [UnwrapException] if the [Result] is [Ok].
+ * @throws UnwrapException if the [Result] is [Ok], with the specified [message].
  */
 infix fun <V, E> Result<V, E>.expectError(message: String): E {
     return when (this) {