Improve documentation

Author: Virtlink

disjointmap/src/main/kotlin/net/pelsmaeker/collections/DisjointMapImpl.kt

@@ -6,14 +6,14 @@ import kotlinx.collections.immutable.toPersistentSet
  * Finds the representative key for the given key
  * and performs path compression.
  *
- * @param key the key for which to find the representative key
- * @param roots the map from sets to their values
- * @param parents the mutable map from keys to their parent key
- * @param ranks the mutable map from keys to their ranks
- * @param K the type of keys
- * @param V the type of values
- * @return the representative key, or the given key when it's
- * its own representative; or `null` when the key was not found
+ * @param K The type of keys.
+ * @param V The type of values.
+ * @param key The key for which to find the representative key.
+ * @param roots The map from sets to their values.
+ * @param parents The mutable map from keys to their parent key.
+ * @param ranks The mutable map from keys to their ranks.
+ * @return The representative key, or the given key when it's
+ * its own representative; or `null` when the key was not found.
  */
 internal fun <K, V> findMutable(
     key: K,
@@ -50,19 +50,19 @@ internal fun <K, V> findMutable(
  *
  * When one or both of the keys don't exist in the map, they are added.
  *
- * @param key1 the first key
- * @param key2 the second key
- * @param default function that provides a default value
- * @param compare function that compares the keys: the higher is used as the new representative;
- * or 0 to use the rank to determine this
- * @param unify function that unifies the associated values of each of the sets,
- * where the first value is from the representative
- * @param roots the mutable map from sets to their values
- * @param parents the mutable map from keys to their parent key
- * @param ranks the mutable map from keys to their ranks
- * @param K the type of keys
- * @param V the type of values
- * @return whether disjoint sets have been unified
+ * @param K The type of keys.
+ * @param V The type of values.
+ * @param key1 The first key.
+ * @param key2 The second key.
+ * @param default Function that provides a default value.
+ * @param compare Function that compares the keys: the higher is used as the new representative;
+ * or 0 to use the rank to determine this.
+ * @param unify Function that unifies the associated values of each of the sets,
+ * where the first value is from the representative.
+ * @param roots The mutable map from sets to their values.
+ * @param parents The mutable map from keys to their parent key.
+ * @param ranks The mutable map from keys to their ranks.
+ * @return Whether disjoint sets have been unified.
  */
 @Suppress("UNCHECKED_CAST")
 internal fun <K, V> unionMutable(
@@ -132,13 +132,13 @@ internal fun <K, V> unionMutable(
  * This will create a new set with the given key and the value of the original set.
  * When the key doesn't exist, nothing happens.
  *
- * @param key the key to disunify
- * @param roots the mutable map from sets to their values
- * @param parents the mutable map from keys to their parent key
- * @param ranks the mutable map from keys to their ranks
- * @param K the type of keys
- * @param V the type of values
- * @return whether the key was in the map
+ * @param K The type of keys.
+ * @param V The type of values.
+ * @param key The key to disunify.
+ * @param roots The mutable map from sets to their values.
+ * @param parents The mutable map from keys to their parent key.
+ * @param ranks The mutable map from keys to their ranks.
+ * @return Whether the key was in the map.
  */
 internal fun <K, V> disunionMutable(key: K, roots: MutableMap<K, V>, parents: MutableMap<K, K>, ranks: MutableMap<K, Int>): Boolean {
     var rep: K = findMutable(key, roots, parents, ranks) ?: return false
@@ -171,14 +171,14 @@ internal fun <K, V> disunionMutable(key: K, roots: MutableMap<K, V>, parents: Mu
  *
  * When the key doesn't exist in the map, it is added.
  *
- * @param key the key of the set to set
- * @param value the value to associate with the set
- * @param roots the mutable map from sets to their values
- * @param parents the mutable map from keys to their parent key
- * @param ranks the mutable map from keys to their ranks
- * @param K the type of keys
- * @param V the type of values
- * @return the old value associated with the key; or `null`
+ * @param K The type of keys.
+ * @param V The type of values.
+ * @param key The key of the set to set.
+ * @param value The value to associate with the set.
+ * @param roots The mutable map from sets to their values.
+ * @param parents The mutable map from keys to their parent key.
+ * @param ranks The mutable map from keys to their ranks.
+ * @return The old value associated with the key; or `null`.
  */
 internal fun <K, V> setMutable(key: K, value: V, roots: MutableMap<K, V>, parents: MutableMap<K, K>, ranks: MutableMap<K, Int>): V? {
     val rep = findMutable(key, roots, parents, ranks) ?: key
@@ -192,11 +192,11 @@ internal fun <K, V> setMutable(key: K, value: V, roots: MutableMap<K, V>, parent
  *
  * When the key doesn't exist in the map, it is added.
  *
- * @param rep the representative element of the set to set
- * @param value the value to associate with the set
- * @param roots the mutable map from sets to their values
- * @param K the type of keys
- * @param V the type of values
+ * @param K The type of keys.
+ * @param V The type of values.
+ * @param rep The representative element of the set to set.
+ * @param value The value to associate with the set.
+ * @param roots The mutable map from sets to their values.
  */
 internal fun <K, V> setMutableRep(rep: K, value: V, roots: MutableMap<K, V>) {
     roots[rep] = value
@@ -207,13 +207,13 @@ internal fun <K, V> setMutableRep(rep: K, value: V, roots: MutableMap<K, V>) {
  *
  * When the key is the last key of a set, the set is removed.
  *
- * @param key the key to remove
- * @param roots the mutable map from sets to their values
- * @param parents the mutable map from keys to their parent key
- * @param ranks the mutable map from keys to their ranks
- * @param K the type of keys
- * @param V the type of values
- * @return the value of the set from which the key was removed; or `null` when the key was not found
+ * @param K The type of keys.
+ * @param V The type of values.
+ * @param key The key to remove.
+ * @param roots The mutable map from sets to their values.
+ * @param parents The mutable map from keys to their parent key.
+ * @param ranks The mutable map from keys to their ranks.
+ * @return The value of the set from which the key was removed; or `null` when the key was not found.
  */
 internal fun <K, V> removeMutable(
     key: K,
@@ -230,7 +230,7 @@ internal fun <K, V> removeMutable(
 /**
  * Copies the sets from this disjoint map to a new map.
  *
- * @return the new map
+ * @return The new map.
  */
 internal fun <K, V> DisjointMap<K, V>.toMapImpl(
     roots: Map<K, V>,

disjointmap/src/main/kotlin/net/pelsmaeker/collections/DisjointMaps.kt

@@ -5,19 +5,19 @@ package net.pelsmaeker.collections
 /**
  * Returns an empty persistent disjoint map.
  *
- * @param K the type of keys
- * @param V the type of values
- * @return an empty persistent disjoint map
+ * @param K The type of keys.
+ * @param V The type of values.
+ * @return An empty persistent disjoint map.
  */
 fun <K, V> persistentDisjointMapOf(): PersistentDisjointMap<K, V> = PersistentUnionFindMap.emptyOf()
 
 /**
  * Returns a persistent disjoint map with the given sets.
  *
- * @param pairs the pairs of sets, consisting of a set of keys and an associated value
- * @param K the type of keys
- * @param V the type of values
- * @return the created persistent disjoint map
+ * @param pairs The pairs of sets, consisting of a set of keys and an associated value.
+ * @param K The type of keys.
+ * @param V The type of values.
+ * @return The created persistent disjoint map.
  */
 fun <K, V> persistentDisjointMapOf(vararg pairs: Pair<Set<K>, V>): PersistentDisjointMap<K, V> {
     return pairs.asIterable().toPersistentDisjointMap()
@@ -26,19 +26,19 @@ fun <K, V> persistentDisjointMapOf(vararg pairs: Pair<Set<K>, V>): PersistentDis
 /**
  * Returns an empty mutable disjoint map.
  *
- * @param K the type of keys
- * @param V the type of values
- * @return an empty mutable disjoint map
+ * @param K The type of keys.
+ * @param V The type of values.
+ * @return An empty mutable disjoint map.
  */
 fun <K, V> mutableDisjointMapOf(): MutableDisjointMap<K, V> = MutableUnionFindMap()
 
 /**
  * Returns a mutable disjoint map with the given sets.
  *
- * @param pairs the pairs of sets, consisting of a set of keys and an associated value
- * @param K the type of keys
- * @param V the type of values
- * @return the created mutable disjoint map
+ * @param pairs The pairs of sets, consisting of a set of keys and an associated value.
+ * @param K The type of keys.
+ * @param V The type of values.
+ * @return The created mutable disjoint map.
  */
 fun <K, V> mutableDisjointMapOf(vararg pairs: Pair<Set<K>, V>): MutableDisjointMap<K, V> {
     return pairs.asIterable().toMutableDisjointMap()
@@ -49,9 +49,9 @@ fun <K, V> mutableDisjointMapOf(vararg pairs: Pair<Set<K>, V>): MutableDisjointM
  *
  * If the receiver is already an immutable disjoint map, it is returned as-is.
  *
- * @param K the type of keys
- * @param V the type of values
- * @return the resulting immutable disjoint map
+ * @param K The type of keys.
+ * @param V The type of values.
+ * @return The resulting immutable disjoint map.
  */
 fun <K, V> DisjointMap<K, V>.toImmutableDisjointMap(): ImmutableDisjointMap<K, V> {
     return this as? ImmutableDisjointMap<K, V> ?: this.toPersistentDisjointMap()
@@ -63,9 +63,9 @@ fun <K, V> DisjointMap<K, V>.toImmutableDisjointMap(): ImmutableDisjointMap<K, V
  * If the receiver is already a persistent disjoint map, it is returned as-is.
  * If the receiver is a persistent disjoint map builder, the result of calling its [PersistentDisjointMap.Builder.build] method is returned.
  *
- * @param K the type of keys
- * @param V the type of values
- * @return the resulting persistent disjoint map
+ * @param K The type of keys.
+ * @param V The type of values.
+ * @return The resulting persistent disjoint map.
  */
 fun <K, V> DisjointMap<K, V>.toPersistentDisjointMap(): PersistentDisjointMap<K, V> {
     return this as? PersistentDisjointMap<K, V>
@@ -76,9 +76,9 @@ fun <K, V> DisjointMap<K, V>.toPersistentDisjointMap(): PersistentDisjointMap<K,
 /**
  * Returns the given map of sets as a persistent disjoint map.
  *
- * @param K the type of keys
- * @param V the type of values
- * @return the resulting persistent disjoint map
+ * @param K The type of keys.
+ * @param V The type of values.
+ * @return The resulting persistent disjoint map.
  */
 fun <K, V> Map<Set<K>, V>.toPersistentDisjointMap(): PersistentDisjointMap<K, V> {
     return this.entries.map { it.toPair() }.toPersistentDisjointMap()
@@ -87,9 +87,9 @@ fun <K, V> Map<Set<K>, V>.toPersistentDisjointMap(): PersistentDisjointMap<K, V>
 /**
  * Returns the given map of sets as a mutable disjoint map.
  *
- * @param K the type of keys
- * @param V the type of values
- * @return the resulting mutable disjoint map
+ * @param K The type of keys.
+ * @param V The type of values.
+ * @return The resulting mutable disjoint map.
  */
 private fun <K, V> Map<Set<K>, V>.toMutableDisjointMap(): MutableDisjointMap<K, V> {
     return this.entries.map { it.toPair() }.toMutableDisjointMap()
@@ -98,9 +98,9 @@ private fun <K, V> Map<Set<K>, V>.toMutableDisjointMap(): MutableDisjointMap<K,
 /**
  * Returns the given iterable of pairs of a set of keys and a value as a persistent disjoint map.
  *
- * @param K the type of keys
- * @param V the type of values
- * @return the resulting persistent disjoint map
+ * @param K The type of keys.
+ * @param V The type of values.
+ * @return The resulting persistent disjoint map.
  */
 fun <K, V> Iterable<Pair<Set<K>, V>>.toPersistentDisjointMap(): PersistentDisjointMap<K, V> {
     return PersistentUnionFindMap.emptyOf<K, V>().builder().addSets(this).build()
@@ -109,9 +109,9 @@ fun <K, V> Iterable<Pair<Set<K>, V>>.toPersistentDisjointMap(): PersistentDisjoi
 /**
  * Returns the given iterable of pairs of a set of keys and a value as a mutable disjoint map.
  *
- * @param K the type of keys
- * @param V the type of values
- * @return the resulting mutable disjoint map
+ * @param K The type of keys.
+ * @param V The type of values.
+ * @return The resulting mutable disjoint map.
  */
 private fun <K, V> Iterable<Pair<Set<K>, V>>.toMutableDisjointMap(): MutableDisjointMap<K, V> {
     return mutableDisjointMapOf<K, V>().addSets(this)
@@ -120,10 +120,10 @@ private fun <K, V> Iterable<Pair<Set<K>, V>>.toMutableDisjointMap(): MutableDisj
 /**
  * Adds the given sets to the mutable disjoint map.
  *
- * @param sets the sets to add, an iterable of pairs of a set of keys and a value
- * @param K the type of keys
- * @param V the type of values
- * @return the receiver
+ * @param sets The sets to add, an iterable of pairs of a set of keys and a value.
+ * @param K The type of keys.
+ * @param V The type of values.
+ * @return The receiver.
  */
 private fun <K, V, T: MutableDisjointMap<K, V>> T.addSets(sets: Iterable<Pair<Set<K>, V>>): T {
     for ((keys, value) in sets) {
@@ -140,10 +140,10 @@ private fun <K, V, T: MutableDisjointMap<K, V>> T.addSets(sets: Iterable<Pair<Se
  *
  * The mutable disjoint map passed to [mutator] had the same contents as the persistent disjoint map.
  *
- * @param mutator the closure that mutates the map
- * @param K the type of keys
- * @param V the type of values
- * @return a persistent disjoint map with the modifications applied
+ * @param mutator The closure that mutates the map.
+ * @param K The type of keys.
+ * @param V The type of values.
+ * @return A persistent disjoint map with the modifications applied.
  */
 inline fun <K, V> PersistentDisjointMap<K, V>.mutate(mutator: (MutableDisjointMap<K, V>) -> Unit): PersistentDisjointMap<K, V>
         = this.builder().apply(mutator).build()

disjointmap/src/main/kotlin/net/pelsmaeker/collections/ImmutableDisjointMap.kt

@@ -13,7 +13,7 @@ interface ImmutableDisjointMap<K, out V> : DisjointMap<K, V> {
     /**
      * Copies the sets from this disjoint map to a new map.
      *
-     * @return the new map
+     * @return The new map.
      */
     override fun toMap(): ImmutableMap<Set<K>, V>