From c5a11a914e730004f63f6e5f7a0ccbad57a054fe Mon Sep 17 00:00:00 2001 From: Michael Bull Date: Tue, 9 Jan 2018 21:20:00 +0000 Subject: [PATCH] Simplify doc comments according to Kotlin Coding Conventions https://kotlinlang.org/docs/reference/coding-conventions.html#documentation-comments --- .../com/github/michaelbull/result/And.kt | 6 --- .../com/github/michaelbull/result/Get.kt | 10 ----- .../com/github/michaelbull/result/Iterable.kt | 38 ++----------------- .../com/github/michaelbull/result/Map.kt | 17 --------- .../com/github/michaelbull/result/On.kt | 2 - .../com/github/michaelbull/result/Or.kt | 6 --- .../com/github/michaelbull/result/Result.kt | 6 +-- .../michaelbull/result/ResultIterator.kt | 10 ++--- 8 files changed, 10 insertions(+), 85 deletions(-) diff --git a/src/main/kotlin/com/github/michaelbull/result/And.kt b/src/main/kotlin/com/github/michaelbull/result/And.kt index fcffb58..518d4d7 100644 --- a/src/main/kotlin/com/github/michaelbull/result/And.kt +++ b/src/main/kotlin/com/github/michaelbull/result/And.kt @@ -9,9 +9,6 @@ infix fun Result.and(result: Result): 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]. - * @return The [result] if [Ok], otherwise [Err]. */ infix inline fun Result.and(result: () -> Result): Result { return when (this) { @@ -26,9 +23,6 @@ infix inline fun Result.and(result: () -> Result): Result Result.andThen(transform: (V) -> Result): Result { return when (this) { diff --git a/src/main/kotlin/com/github/michaelbull/result/Get.kt b/src/main/kotlin/com/github/michaelbull/result/Get.kt index 197fffb..5c9c118 100644 --- a/src/main/kotlin/com/github/michaelbull/result/Get.kt +++ b/src/main/kotlin/com/github/michaelbull/result/Get.kt @@ -5,8 +5,6 @@ package com.github.michaelbull.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 Result.get(): V? { return when (this) { @@ -19,8 +17,6 @@ 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`. */ fun Result.getError(): E? { return when (this) { @@ -77,9 +73,6 @@ infix inline fun Result.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][Err.error]. - * @return The [value][Ok.value] if [Ok], otherwise the [transformed][transform] [error][Err.error]. */ infix inline fun Result.getOrElse(transform: (E) -> V): V { return when (this) { @@ -91,9 +84,6 @@ 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]. */ infix inline fun Result.getErrorOrElse(transform: (V) -> E): E { return when (this) { diff --git a/src/main/kotlin/com/github/michaelbull/result/Iterable.kt b/src/main/kotlin/com/github/michaelbull/result/Iterable.kt index 3554cda..71660ce 100644 --- a/src/main/kotlin/com/github/michaelbull/result/Iterable.kt +++ b/src/main/kotlin/com/github/michaelbull/result/Iterable.kt @@ -1,11 +1,7 @@ package com.github.michaelbull.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. + * Accumulates value starting with [initial] value and applying [operation] from left to right to current accumulator value and each element. */ inline fun Iterable.fold( initial: R, @@ -28,11 +24,7 @@ inline fun Iterable.fold( } /** - * 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. + * Accumulates value starting with [initial] value and applying [operation] from right to left to each element and current accumulator value. */ inline fun List.foldRight( initial: R, @@ -58,21 +50,16 @@ inline fun List.foldRight( } /** - * Combine a vararg of [Results][Result] into a single [Result] (holding a [List]). + * Combines 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 combine(vararg results: Result) = results.asIterable().combine() /** - * Combine an [Iterable] of [Results][Result] into a single [Result] (holding a [List]). + * Combines 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 Iterable>.combine(): Result, E> { return Ok(map { @@ -88,9 +75,6 @@ fun Iterable>.combine(): Result, E> { * 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 getAll(vararg results: Result) = results.asIterable().getAll() @@ -99,8 +83,6 @@ fun getAll(vararg results: Result) = results.asIterable().getAll() * 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 Iterable>.getAll(): List { return filterIsInstance>().map { it.value } @@ -111,9 +93,6 @@ fun Iterable>.getAll(): List { * 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 [Err] elements. - * @return The extracted [Err] elements. */ fun getAllErrors(vararg results: Result) = results.asIterable().getAllErrors() @@ -122,8 +101,6 @@ fun getAllErrors(vararg results: Result) = results.asIterable().get * 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 [Err] elements. */ fun Iterable>.getAllErrors(): List { return filterIsInstance>().map { it.error } @@ -135,10 +112,6 @@ fun Iterable>.getAllErrors(): List { * 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 [Err] elements. */ fun partition(vararg results: Result) = results.asIterable().partition() @@ -148,9 +121,6 @@ fun partition(vararg results: Result) = results.asIterable().partit * 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 [Err] elements. */ fun Iterable>.partition(): Pair, List> { val values = mutableListOf() diff --git a/src/main/kotlin/com/github/michaelbull/result/Map.kt b/src/main/kotlin/com/github/michaelbull/result/Map.kt index 409dedc..b51e64b 100644 --- a/src/main/kotlin/com/github/michaelbull/result/Map.kt +++ b/src/main/kotlin/com/github/michaelbull/result/Map.kt @@ -7,9 +7,6 @@ package com.github.michaelbull.result * - 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 Result.map(transform: (V) -> U): Result { return when (this) { @@ -25,9 +22,6 @@ infix inline fun Result.map(transform: (V) -> U): Result { * - 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][Err.error]. - * @return The [value][Ok.value] if [Ok], otherwise the [transformed][transform] [Err]. */ infix inline fun Result.mapError(transform: (E) -> F): Result { return when (this) { @@ -43,10 +37,6 @@ infix inline fun Result.mapError(transform: (E) -> F): Result Result.mapBoth( success: (V) -> U, @@ -64,10 +54,6 @@ inline fun Result.mapBoth( * 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) - * - * @param success The function to apply to `V` if [Ok]. - * @param failure The function to apply to `E` if [Err]. - * @return The mapped [Result]. */ inline fun Result.mapEither( success: (V) -> U, @@ -86,9 +72,6 @@ inline fun Result.mapEither( * This is functionally equivalent to [andThen]. * * - Scala: [Either.flatMap](http://www.scala-lang.org/api/2.12.0/scala/util/Either.html#flatMap[AA>:A,Y](f:B=>scala.util.Either[AA,Y]):scala.util.Either[AA,Y]) - * - * @param transform The transformation to apply to the [value][Ok.value]. - * @return The [transformed][transform] [Result] if [Ok], otherwise [Err]. */ infix inline fun Result.flatMap(transform: (V) -> Result): Result { return andThen(transform) diff --git a/src/main/kotlin/com/github/michaelbull/result/On.kt b/src/main/kotlin/com/github/michaelbull/result/On.kt index 4dbe32c..c0577b1 100644 --- a/src/main/kotlin/com/github/michaelbull/result/On.kt +++ b/src/main/kotlin/com/github/michaelbull/result/On.kt @@ -2,12 +2,10 @@ package com.github.michaelbull.result /** * Invokes a [callback] if this [Result] is [Ok]. - * @param callback The function to call. */ infix inline fun Result.onSuccess(callback: (V) -> Unit) = mapBoth(callback, {}) /** * 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 e1f6c56..6c7c17a 100644 --- a/src/main/kotlin/com/github/michaelbull/result/Or.kt +++ b/src/main/kotlin/com/github/michaelbull/result/Or.kt @@ -9,9 +9,6 @@ infix fun Result.or(result: Result): 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]. - * @return The [result] if [Err], otherwise [Ok]. */ infix inline fun Result.or(result: () -> Result): Result { return when (this) { @@ -25,9 +22,6 @@ infix inline fun Result.or(result: () -> Result): Result Result.orElse(transform: (E) -> Result): Result { return when (this) { diff --git a/src/main/kotlin/com/github/michaelbull/result/Result.kt b/src/main/kotlin/com/github/michaelbull/result/Result.kt index ee94549..44b14af 100644 --- a/src/main/kotlin/com/github/michaelbull/result/Result.kt +++ b/src/main/kotlin/com/github/michaelbull/result/Result.kt @@ -27,9 +27,9 @@ sealed class Result { /** * Represents a successful [Result], containing a [value]. */ -data class Ok constructor(val value: V) : Result() +data class Ok(val value: V) : Result() /** - * Represents a failed [Result], containing an [error] value. + * Represents a failed [Result], containing an [error]. */ -data class Err constructor(val error: E) : Result() +data class Err(val error: E) : Result() diff --git a/src/main/kotlin/com/github/michaelbull/result/ResultIterator.kt b/src/main/kotlin/com/github/michaelbull/result/ResultIterator.kt index 396b232..aecb10a 100644 --- a/src/main/kotlin/com/github/michaelbull/result/ResultIterator.kt +++ b/src/main/kotlin/com/github/michaelbull/result/ResultIterator.kt @@ -1,24 +1,20 @@ package com.github.michaelbull.result /** - * Creates an [Iterator] over the possibly contained [value][Ok.value]. + * Returns 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 Result.iterator(): Iterator { return ResultIterator(this) } /** - * Creates a [MutableIterator] over the possibly contained [value][Ok.value]. + * Returns 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 Result.mutableIterator(): MutableIterator { return ResultIterator(this) @@ -46,7 +42,7 @@ private class ResultIterator(private val result: Result) : M } /** - * @return The [Result's][Result] [value][Ok.value] if not [yielded] and [Ok]. + * Returns 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 {