Improve kdocs

Author: mandrean

src/main/kotlin/io/vavr/kotlin/Collections.kt

@@ -31,120 +31,154 @@ import io.vavr.collection.Stream
  */
 
 /**
+ * Creates a [List] of the given elements.
+ *
  * @see List.of
  */
 fun <T> list(vararg t: T):
     List<T> = List.of(*t)
 
 /**
- * Converts a Value (that is, _any_ Vavr data class) into a Kotlin MutableList
+ * Converts a Vavr [Value] (that is, _any_ Vavr data class) into a Kotlin [MutableList].
  */
 fun <T> Value<T>.toMutableList():
     MutableList<T> = this.toJavaList().toMutableList()
 
 /**
- * Converts a Kotlin Iterable into a List
+ * Converts a Kotlin [Iterable] into a Vavr [List].
+ *
+ * @see List.ofAll
  */
 fun <T> Iterable<T>.toVavrList():
     List<T> = List.ofAll(this)
 
 /**
- * Converts a Kotlin Array into a List
+ * Converts a Kotlin [Array] into a Vavr [List].
+ *
+ * @see List.ofAll
  */
 fun <T> Array<T>.toVavrList():
     List<T> = List.ofAll(this.asIterable())
 
 /**
+ * Creates a Vavr [Stream] of the given elements.
+ *
  * @see Stream.of
  */
 fun <T> stream(vararg t: T):
     Stream<T> = Stream.of(*t)
 
 /**
+ * Converts a Kotlin [Iterable] into a Vavr [Stream].
+ *
  * @see Stream.ofAll
  */
 fun <T> Iterable<T>.toVavrStream():
     Stream<T> = Stream.ofAll(this)
 
 /**
- * Converts a Kotlin Array into a Stream
+ * Converts a Kotlin [Array] into a Vavr [Stream].
+ *
+ * @see Stream.ofAll
  */
 fun <T> Array<T>.toVavrStream():
     Stream<T> = Stream.ofAll(this.asIterable())
 
 /**
- * Converts a Kotlin Sequence into a Stream
+ * Converts a Kotlin [Sequence] into a Vavr [Stream].
+ *
+ * @see Stream.ofAll
  */
 fun <T> Sequence<T>.toVavrStream():
     Stream<T> = Stream.ofAll(this.asIterable())
 
 /**
- * Converts a Kotlin Map into a Vavr Map
+ * Converts a Kotlin [kotlin.collections.Map] into a Vavr [Map].
+ *
+ * @see HashMap.ofAll
  */
 fun <K, V> kotlin.collections.Map<K, V>.toVavrMap():
     io.vavr.collection.Map<K, V> = io.vavr.collection.HashMap.ofAll(this)
 
 /**
- * Converts a Vavr Map to a Kotlin MutableMap
+ * Converts a Vavr [Map] to a Kotlin [MutableMap].
  */
 fun <K, V> io.vavr.collection.Map<K, V>.toMutableMap():
     kotlin.collections.MutableMap<K, V> = this.toJavaMap().toMutableMap()
 
 /**
- * Creates a Vavr HashMap from a series of Kotlin Pairs
+ * Creates a Vavr [HashMap] from a series of Kotlin [Pair]s.
  */
 fun <K, V> hashMap(vararg p: Pair<K, V>):
     io.vavr.collection.HashMap<K, V> =
         io.vavr.collection.HashMap.ofEntries(p.asIterable().map { it.tuple() })
 
 /**
- * Creates a Vavr LinkedHashMap from a series of Kotlin Pairs
+ * Creates a Vavr [LinkedHashMap] from a series of Kotlin [Pair]s.
  */
 fun <K, V> linkedHashMap(vararg p: Pair<K, V>):
     io.vavr.collection.LinkedHashMap<K, V> =
         io.vavr.collection.LinkedHashMap.ofEntries(p.asIterable().map { it.tuple() })
 
 /**
- * Creates a Vavr TreeMap from a series of Kotlin Pairs.
- * Notice that the keys of a TreeMap must be Comparable
+ * Creates a Vavr [TreeMap] from a series of Kotlin [Pair]s.
+ *
+ * Note that the keys of a [TreeMap] must be [Comparable].
+ *
+ * @param K a [Comparable] key
+ * @see TreeMap.ofEntries
  */
 fun <K : Comparable<K>, V> treeMap(vararg p: Pair<K, V>):
     io.vavr.collection.TreeMap<K, V> =
         io.vavr.collection.TreeMap.ofEntries(p.asIterable().map { it.tuple() })
 
 /**
- * Returns the value associated with a key, or null if the key is not contained in the map.
+ * Returns the value associated with a key, or null if the key is not contained in the [Map].
+ *
+ * @see Map.getOrElse
  */
 fun <K, V> Map<K, V>.getOrNull(key: K):
     V? = this.getOrElse(key, null)
 
 /**
- * Converts a Kotlin Set into a Vavr Set
+ * Creates a Vavr [HashSet] of the given elements.
+ *
+ * @see HashSet.ofAll
  */
 fun <T> kotlin.collections.Set<T>.toVavrSet():
     io.vavr.collection.Set<T> = io.vavr.collection.HashSet.ofAll(this)
 
 /**
- * Converts a Vavr Set into a Kotlin MutableSet
+ * Converts a Kotlin [Array] into a Vavr [Set].
+ *
+ * @see HashSet.ofAll
  */
 fun <T> io.vavr.collection.Set<T>.toMutableSet():
     kotlin.collections.MutableSet<T> = this.toJavaSet().toMutableSet()
 
 /**
- * Creates a Vavr HashSet
+ * Converts a Kotlin [Sequence] into a Vavr [List].
+ *
+ * @see HashSet.ofAll
  */
 fun <T> hashSet(vararg t: T):
     io.vavr.collection.HashSet<T> = io.vavr.collection.HashSet.ofAll(t.asIterable())
 
 /**
- * Creates a Vavr LinkedHashSet
+ * Creates a Vavr [LinkedHashSet] of the given elements.
+ *
+ * @see LinkedHashSet.ofAll
  */
 fun <T> linkedHashSet(vararg t: T):
     io.vavr.collection.LinkedHashSet<T> = io.vavr.collection.LinkedHashSet.ofAll(t.asIterable())
 
 /**
- * Creates a Vavr TreeSet.
- * Notice that the elements of a TreeSet must be Comparable
+ * Creates a Vavr [TreeSet] from a series of Kotlin [Pair]s.
+ *
+ * Note that the elements of a [TreeSet] must be [Comparable].
+ *
+ * @param t a [Comparable] element
+ * @see TreeSet.ofAll
  */
 fun <T : Comparable<T>> treeSet(vararg t: T):
     io.vavr.collection.TreeSet<T> =

src/main/kotlin/io/vavr/kotlin/Control.kt

@@ -35,8 +35,9 @@ import io.vavr.control.Validation
  */
 
 /**
- * Creates an Option of a nullable.
- * @return None() for null, Some(this) for a present value
+ * Creates an [Option] of a nullable.
+ *
+ * @return [Option.none] for null or [Option.some] for a present value.
  */
 fun <A> A?.option():
     Option<A> = if (this == null) none() else some(this)
@@ -54,15 +55,17 @@ fun <A> none():
     Option<A> = Option.none()
 
 /**
- * Creates an Option predicated on a Boolean, using the supplied value.
- * @return Some(a) if this is true, None() otherwise
+ * Creates an [Option] predicated on a Boolean, using the supplied value.
+ *
+ * @return [Option.some] if this is true, otherwise [Option.none].
  */
 fun <A> Boolean.option(a: A):
     Option<A> = if (this) some(a) else none()
 
 /**
- * Creates an Option predicated on a Boolean, using the supplier of value.
- * @return Some(a.invoke()) if this is true, None() otherwise
+ * Creates an [Option] predicated on a Boolean, using the supplier of value.
+ *
+ * @return [Some(a.invoke())][Option.some] if this is true, otherwise [Option.none].
  */
 fun <A> Boolean.option(a: () -> A):
     Option<A> = if (this) some(a.invoke()) else none()

src/main/kotlin/io/vavr/kotlin/Tuples.kt

@@ -22,7 +22,7 @@ package io.vavr.kotlin
 import io.vavr.*
 
 /**
- * Constructors and sequence() extensions for the Vavr Tuple
+ * Constructors and sequence() extensions for the Vavr Tuple.
  *
  * @author Alex Zuzin (github.com/zvozin)
  */
@@ -76,13 +76,15 @@ fun <T1, T2, T3, T4, T5, T6, T7, T8> tuple(t1: T1, t2: T2, t3: T3, t4: T4, t5: T
     Tuple8<T1, T2, T3, T4, T5, T6, T7, T8> = Tuple.of(t1, t2, t3, t4, t5, t6, t7, t8)
 
 /**
- * Creates a Tuple out of a Kotlin Pair
+ * Creates a [Tuple] out of a Kotlin [Pair].
+ *
+ * @see Tuple.of
  */
 fun <T1, T2> Pair<T1, T2>.tuple():
     Tuple2<T1, T2> = Tuple.of(this.first, this.second)
 
 /**
- * Creates a Kotlin Pair out of a Tuple
+ * Creates a Kotlin [Pair] out of a [Tuple].
  */
 fun <T1, T2> Tuple2<T1, T2>.pair():
     Pair<T1, T2> = Pair(this._1, this._2)