Update docstrings

src/main/kotlin/moe/kageru/sekwences/Sekwences.kt

@@ -4,6 +4,11 @@ package moe.kageru.sekwences
  * Returns a sequences that optionally merges adjacent elements.
  * Heavily inspired by Itertools.coalesce() from the Rust crate.
  *
+ * The merge function will be passed two adjacent elements in the sequence.
+ * If the two can be merged, the result of the merging process should be returned.
+ * If null is returned, the first of the two elements is returned,
+ * and the second will be used as the first element in the next merge operation.
+ *
  * https://docs.rs/itertools/0.8.0/itertools/trait.Itertools.html#method.coalesce
  */
 fun <T> Sequence<T>.coalesce(merger: (T, T) -> T?): Sequence<T> {
@@ -14,14 +19,21 @@ fun <T> Sequence<T>.coalesce(merger: (T, T) -> T?): Sequence<T> {
     }
 }
 
-class CoalescingSequence<T>(private val source: Sequence<T>, private inline val merger: (T, T) -> T?) : Sequence<T> {
+/**
+ * Sequence that holds a [CoalescingIterator].
+ */
+internal class CoalescingSequence<T>(private val source: Sequence<T>, private inline val merger: (T, T) -> T?) : Sequence<T> {
     override fun iterator(): Iterator<T> {
         return CoalescingIterator(source.iterator(), merger)
     }
 }
 
-class CoalescingIterator<T>(private val source: Iterator<T>, private inline val merger: (T, T) -> T?) : Iterator<T> {
+/**
+ * Iterator that will attempt to merge adjacent elements as described in the KDoc for [coalesce].
+ */
+internal class CoalescingIterator<T>(private val source: Iterator<T>, private inline val merger: (T, T) -> T?) : Iterator<T> {
     private var previous: T = if (source.hasNext()) source.next() else error("Please don’t pass empty iterators in here")
+    // The reason we need this marker is that our iterator can still hold one value, even if the source has been drained.
     private var hasNext = true
 
     override fun hasNext() = hasNext

src/test/kotlin/moe/kageru/sekwences/SekwencesTest.kt

@@ -45,4 +45,4 @@ class SekwencesTest : ShouldSpec({
         }.toList()
         output shouldBe input
     }
-})
+})