text-files-util: minor fixing k-docs

src/main/kotlin/files/Files.kt

@@ -19,7 +19,7 @@ import kotlin.io.path.fileSize
 import kotlin.io.path.inputStream
 
 /**
- * Inserts the given [lines] before the specified [position] in assumption
+ * Inserts given [lines] before the specified [position] in assumption
  * that [target] file contains lines separated by [delimiter] and
  * the given [position] is a first byte of some line (or the size of the file to insert at its end).
  * @param target [Path]
@@ -47,7 +47,7 @@ fun insertLines(
 }
 
 /**
- * Inserts the given [data] at the [specified position][beforePosition] of channel.
+ * Inserts the given [data] at the [specified position][beforePosition] of the channel.
  *
  * @param [data][ByteArray] to write
  * @param [beforePosition][Long] the position in the source before which the data should be inserted
@@ -118,8 +118,8 @@ fun SeekableByteChannel.insert(
  * Inverts the file content, `a,b,c` -> `c,b,a`
  * @param [source][Path]
  * @param [target][Path]
- * @param [deleteSourceFiles] if `true` source files will be truncated while process and completely deleted at the end of it;
- * this allows to save diskspace
+ * @param [deleteSourceFiles] if `true` source files will be truncated while processing and completely deleted at the end of it;
+ * this allows saving diskspace
  * @param [delimiter]
  * @param [charset][Charset]
  */
@@ -190,7 +190,7 @@ fun isSorted(
 }
 
 /**
- * Answers `true` if content of two files are identical.
+ * Answers `true` if content of two files is identical.
  */
 fun contentEquals(left: Path, right: Path): Boolean {
     if (left.fileSize() != right.fileSize()) {
@@ -261,7 +261,7 @@ fun Path.channel(
 ): SeekableByteChannel = Files.newByteChannel(this, *options)
 
 /**
- * Determines whether two given paths are equivalent (i.e. specified paths point to a single physical file, possibly non-existent).
+ * Determines whether two given paths are equivalent (i.e., specified paths point to a single physical file, possibly non-existent).
  */
 fun sameFilePaths(left: Path, right: Path): Boolean = left.normalizeToString() == right.normalizeToString()
 

src/main/kotlin/iterators/ClassicMerge.kt

@@ -5,7 +5,8 @@ package cc.datafabric.textfileutils.iterators
 
 /**
  * Classic merge algorithm for [kotlin-sequences][Sequence].
- * The source data must be sorted, i.e. the next element in the iterator must be less than or equal to the previous element.
+ * The source data must be sorted,
+ * i.e., the next element in the iterator must be less than or equal to the previous element.
  * If given data is not sorted, strange output is expected
  * @param [other][Sequence]<[X]>
  * @param [comparator][Comparator] if not specified the type [X] is required to be [Comparable]
@@ -20,7 +21,8 @@ inline fun <reified X> Sequence<X>.mergeWith(
 
 /**
  * Classic merge algorithm for [kotlin-sequences][Sequence].
- * The source data must be sorted, i.e. the next element in the iterator must be less than or equal to the previous element.
+ * The source data must be sorted,
+ * i.e., the next element in the iterator must be less than or equal to the previous element.
  * @param [sources][Iterable]<[Sequence]<[X]>>
  * @param [comparator][Comparator] if not specified the type [X] is required to be [Comparable]
  * @param [X] must be [Comparable] if no [comparator] is provided
@@ -38,7 +40,8 @@ inline fun <reified X> mergeSequences(
 
 /**
  * Classic merge algorithm for [Iterator].
- * The source data must be sorted, i.e. the next element in the iterator must be less than or equal to the previous element.
+ * The source data must be sorted,
+ * i.e., the next element in the iterator must be less than or equal to the previous element.
  * @param [sources][Iterable]<[Iterator]<[X]>>
  * @param [comparator][Comparator] if not specified the type [X] is required to be [Comparable]
  * @param [X] must be [Comparable] if no [comparator] is provided
@@ -56,7 +59,8 @@ inline fun <reified X> mergeIterators(
 
 /**
  * Classic merge algorithm for [iterators][Iterator].
- * The source data must be sorted, i.e. the next element in the iterator must be greater than or equal to the previous element.
+ * The source data must be sorted,
+ * i.e., the next element in the iterator must be greater than or equal to the previous element.
  * @param [sourceLeft][Iterator]<[X]>
  * @param [sourceRight][Iterator]<[X]>
  * @param [comparator][Comparator] if not specified the type [X] is required to be [Comparable]
@@ -73,8 +77,8 @@ inline fun <reified X> mergeIterators(
 
 /**
  * Classic merge algorithm for [collection][Collection] of [iterators][Iterator].
- * The source iterators must produce sorted sequence of items,
- * i.e. the next element in the iterator must be greater than or equal to the previous element.
+ * The source iterators must produce a sorted sequence of items,
+ * i.e., the next element in the iterator must be greater than or equal to the previous element.
  * @param [sources][Iterable]<[Iterator]<[X]>>
  * @param [comparator][Comparator] if not specified the type [X] is required to be [Comparable]
  * @param [target] storage to write merged data

src/main/kotlin/iterators/Iterators.kt

@@ -145,7 +145,7 @@ fun <T, K> ResourceIterator<T>.associateBy(keySelector: (T) -> K): Map<K, T> = u
 /**
  * Returns a [Map] containing key-value pairs provided by [transform] function
  * applied to elements of the given resource-iterator.
- * If any of two pairs would have the same key the last one gets added to the map.
+ * If any of two pairs have the same key, the last one gets added to the map.
  * The returned map preserves the entry iteration order of the original resource-iterator.
  * The operation is _terminal_.
  */
@@ -157,7 +157,7 @@ fun <T, K, V> ResourceIterator<T>.associate(transform: (T) -> Pair<K, V>): Map<K
  * Returns a new map containing all key-value pairs from the given resource-iterator of pairs.
  *
  * The returned map preserves the entry iteration order of the original resource-iterator.
- * If any of two pairs would have the same key the last one gets added to the map.
+ * If any of two pairs have the same key, the last one gets added to the map.
  */
 fun <K, V> ResourceIterator<Pair<K, V>>.toMap(): Map<K, V> = use {
     asInternalSequence().toMap()
@@ -199,7 +199,7 @@ inline fun <T, R> ResourceIterator<T>.fold(initial: R, operation: (acc: R, T) ->
 }
 
 /**
- * Returns `true` if all elements matches the given [predicate].
+ * Returns `true` if all elements match the given [predicate].
  * The operation is _terminal_.
  */
 inline fun <T> ResourceIterator<T>.all(predicate: (T) -> Boolean): Boolean = use {
@@ -272,7 +272,7 @@ inline fun <X, R> Iterable<ResourceIterator<X>>.use(block: (Iterable<ResourceIte
 
 /**
  * Provides an internal [Sequence] to be used for calling terminal Sequence's methods
- * (i.e. those methods that reach the end of the underlying [ResourceIterator]).
+ * (i.e., those methods that reach the end of the underlying [ResourceIterator]).
  */
 private fun <X> ResourceIterator<X>.asInternalSequence(): Sequence<X> {
     require(this is BaseResourceIterator)

src/main/kotlin/iterators/ResourceIterator.kt

@@ -10,7 +10,7 @@ import java.util.function.Consumer
  *
  * It is not [Sequence] but [Iterator], since we can't control every method of [Sequence].
  *
- * The implementation must [close] the underling resource when there is no more items as well.
+ * The implementation must [close] the underling resource when there are no more items as well.
  * This will make all the _terminal_ operations (e.g. [toList]) and
  * the _intermediate_ operations described by this interface (e.g. [forEach]) safe to use,
  * which means no explicit closing is required (but desirable).

src/main/kotlin/iterators/ResourceIteratorImpls.kt

@@ -96,9 +96,13 @@ internal class FilteringResourceIterator<X>(
     private val predicate: (X) -> Boolean
 ) : WrappedResourceIterator<X>(source, onClose) {
 
-    private var nextState: Int = -1 // -1 for unknown, 0 for done, 1 for continue
     private var nextItem: X? = null
 
+    // `nextState = -1` if iteration is not started yet,
+    // `nextState = 0` if the iterator is done,
+    // `nextState = 1` if the iteration is in progress
+    private var nextState: Int = -1
+
     private fun calcNext() {
         while (source.hasNext()) {
             val item = source.next()
@@ -164,8 +168,13 @@ internal class GeneratorResourceIterator<T>(
     private val getNext: () -> T?,
     onClose: () -> Unit,
 ) : BaseResourceIterator<T>(onClose) {
+
     private var nextItem: T? = null
-    private var nextState: Int = -1 // -1 for next unknown, 0 for done, 1 for continue
+
+    // `nextState = -1` if iteration is not started yet,
+    // `nextState = 0` if the iterator is done,
+    // `nextState = 1` if the iteration is in progress
+    private var nextState: Int = -1
 
     private fun calcNext() {
         nextItem = getNext()

src/main/kotlin/iterators/StepBackIterator.kt

@@ -1,7 +1,7 @@
 package cc.datafabric.textfileutils.iterators
 
 /**
- * An iterator that can return back one step.
+ * An iterator that can take a step back.
  */
 class StepBackIterator<X>(private val base: Iterator<X>) : Iterator<X> {
     private var current: X? = null