From 109de2b4144d37023cec304a615118c98a6d63c6 Mon Sep 17 00:00:00 2001
From: DBotThePony <dbotthepony@yandex.ru>
Date: Thu, 3 Aug 2023 19:50:19 +0700
Subject: [PATCH] Add streamy iterator docs

---
 .../mc/otm/core/collect/StreamyIterator.kt    | 66 +++++++++++++++++--
 1 file changed, 60 insertions(+), 6 deletions(-)

diff --git a/src/main/kotlin/ru/dbotthepony/mc/otm/core/collect/StreamyIterator.kt b/src/main/kotlin/ru/dbotthepony/mc/otm/core/collect/StreamyIterator.kt
index ad729b6d7..1ca57f6a1 100644
--- a/src/main/kotlin/ru/dbotthepony/mc/otm/core/collect/StreamyIterator.kt
+++ b/src/main/kotlin/ru/dbotthepony/mc/otm/core/collect/StreamyIterator.kt
@@ -14,6 +14,11 @@ import java.util.stream.Collector
 
 // Aside parallel work, unimplemented Stream API elements can be easily implemented when required
 
+/**
+ * Filters elements of [parent] iterator
+ *
+ * Resulting [Iterator] is [MutableIterator] if [parent] is
+ */
 class FilteredIterator<T>(private val parent: Iterator<T>, private val predicate: Predicate<in T>) : MutableIterator<T> {
 	private var foundValue: Any? = Companion
 
@@ -66,13 +71,18 @@ class FilteredIterator<T>(private val parent: Iterator<T>, private val predicate
 	private companion object
 }
 
-class MappingIterator<T, R>(private val parent: Iterator<T>, private val transform: (T) -> R) : MutableIterator<R> {
+/**
+ * Maps elements of [parent] iterator from values of [T] to [R] using function [mapper]
+ *
+ * Resulting [Iterator] is [MutableIterator] if [parent] is
+ */
+class MappingIterator<T, R>(private val parent: Iterator<T>, private val mapper: (T) -> R) : MutableIterator<R> {
 	override fun hasNext(): Boolean {
 		return parent.hasNext()
 	}
 
 	override fun next(): R {
-		return transform.invoke(parent.next())
+		return mapper.invoke(parent.next())
 	}
 
 	override fun remove() {
@@ -80,13 +90,18 @@ class MappingIterator<T, R>(private val parent: Iterator<T>, private val transfo
 	}
 }
 
-class FlatMappingIterator<T, R>(private val parent: Iterator<T>, private val transform: (T) -> Iterator<R>) : MutableIterator<R> {
+/**
+ * Maps elements of [parent] iterator from type [T] to other iterators of type [R] using function [mapper]
+ *
+ * Resulting [Iterator] is [MutableIterator] if [parent] is
+ */
+class FlatMappingIterator<T, R>(private val parent: Iterator<T>, private val mapper: (T) -> Iterator<R>) : MutableIterator<R> {
 	private var current: Iterator<R>? = null
 	private var last: Iterator<R>? = null
 
 	override fun hasNext(): Boolean {
 		while (current?.hasNext() != true && parent.hasNext()) {
-			current = transform.invoke(parent.next())
+			current = mapper.invoke(parent.next())
 		}
 
 		return current?.hasNext() == true
@@ -107,7 +122,12 @@ class FlatMappingIterator<T, R>(private val parent: Iterator<T>, private val tra
 	}
 }
 
-class LimitingIterator<T>(val parent: Iterator<T>, val limit: Long) : Iterator<T> {
+/**
+ * Limits amount of values returned by [parent] iterator to return at most [limit] values
+ *
+ * Resulting [Iterator] is [MutableIterator] if [parent] is
+ */
+class LimitingIterator<T>(private val parent: Iterator<T>, private val limit: Long) : Iterator<T> {
 	init {
 		require(limit > 0) { "Invalid limit $limit" }
 	}
@@ -126,7 +146,12 @@ class LimitingIterator<T>(val parent: Iterator<T>, val limit: Long) : Iterator<T
 	}
 }
 
-class SkippingIterator<T>(val parent: Iterator<T>, skip: Long) : MutableIterator<T> {
+/**
+ * Skips (discards) up to [skip] values returned by [parent] iterator
+ *
+ * Resulting [Iterator] is [MutableIterator] if [parent] is
+ */
+class SkippingIterator<T>(private val parent: Iterator<T>, skip: Long) : MutableIterator<T> {
 	init {
 		require(skip >= 0) { "Invalid skip amount $skip" }
 	}
@@ -162,10 +187,39 @@ class SkippingIterator<T>(val parent: Iterator<T>, skip: Long) : MutableIterator
 	}
 }
 
+/**
+ * Filters elements of [this] iterator
+ *
+ * Resulting [Iterator] is [MutableIterator] if [this] is
+ */
 fun <T> Iterator<T>.filter(condition: Predicate<in T>) = FilteredIterator(this, condition)
+
+/**
+ * Maps elements of [this] iterator from values of [T] to [R] using function [mapper]
+ *
+ * Resulting [Iterator] is [MutableIterator] if [this] is
+ */
 fun <T, R> Iterator<T>.map(mapper: (T) -> R) = MappingIterator(this, mapper)
+
+/**
+ * Maps elements of [this] iterator from values of [T] to [R] using function [mapper]
+ *
+ * Resulting [Iterator] is [MutableIterator] if [this] is
+ */
 fun <T, R> Iterator<T>.map(mapper: java.util.function.Function<T, R>) = MappingIterator(this, mapper::apply)
+
+/**
+ * Maps elements of [this] iterator from type [T] to other iterators of type [R] using function [mapper]
+ *
+ * Resulting [Iterator] is [MutableIterator] if [this] is
+ */
 fun <T, R> Iterator<T>.flatMap(mapper: (T) -> Iterator<R>) = FlatMappingIterator(this, mapper)
+
+/**
+ * Maps elements of [this] iterator from type [T] to other iterators of type [R] using function [mapper]
+ *
+ * Resulting [Iterator] is [MutableIterator] if [this] is
+ */
 fun <T, R> Iterator<T>.flatMap(mapper: java.util.function.Function<T, Iterator<R>>) = FlatMappingIterator(this, mapper::apply)
 
 fun interface O2DFunction<T> {