Sequence operation classification regarding their statefulness and laziness.

#KT-16994 Fixed

libraries/stdlib/src/Module.md

@@ -89,6 +89,21 @@ Java reflection provided by `kotlin-reflect` library.
 [Sequence][kotlin.sequences.Sequence] type that represents lazily evaluated collections. Top-level functions for instantiating sequences
 and extension functions for sequences.
 
+## Classification of sequences
+
+The sequence operations can be classified into the following groups regarding their state requirements:
+
+ - _stateless_ – operations like [kotlin.sequences.Sequence.map], [kotlin.sequences.Sequence.filter], which process each element independently;
+ - _nearly stateless_ – operations which require a small constant amount of state to process an element, for example [kotlin.sequences.Sequence.take] or [kotlin.sequences.Sequence.drop];
+ - _stateful_ – operations which require a significant amount of state, usually proportional to the number of elements in a sequence.
+ 
+If the sequence operation returns another sequence, which is produced lazily, it's called _intermediate_, and otherwise the operation is _terminal_.
+Examples of terminal operations are [kotlin.sequences.Sequence.toList], [kotlin.sequences.Sequence.max].
+
+Sequences can be iterated multiple times, however some sequence implementations might constrain themselves
+to be iterated only once. That is mentioned specifically in their documentation (e.g. [kotlin.sequences.generateSequence] overload).
+The latter sequences throw an exception on an attempt to iterate them the second time.
+ 
 # Package kotlin.streams
 
 Utility functions for working with Java 8 [streams](https://docs.oracle.com/javase/8/docs/api/java/util/stream/package-summary.html).

libraries/stdlib/src/kotlin/collections/Sequences.kt

@@ -49,11 +49,15 @@ private object EmptySequence : Sequence<Nothing>, DropTakeSequence<Nothing> {
 
 /**
  * Returns a sequence of all elements from all sequences in this sequence.
+ *
+ * The operation is _intermediate_ and _stateless_.
  */
 public fun <T> Sequence<Sequence<T>>.flatten(): Sequence<T> = flatten { it.iterator() }
 
 /**
  * Returns a sequence of all elements from all iterables in this sequence.
+ *
+ * The operation is _intermediate_ and _stateless_.
  */
 @kotlin.jvm.JvmName("flattenSequenceOfIterable")
 public fun <T> Sequence<Iterable<T>>.flatten(): Sequence<T> = flatten { it.iterator() }
@@ -69,6 +73,8 @@ private fun <T, R> Sequence<T>.flatten(iterator: (T) -> Iterator<R>): Sequence<R
  * Returns a pair of lists, where
  * *first* list is built from the first values of each pair from this sequence,
  * *second* list is built from the second values of each pair from this sequence.
+ *
+ * The operation is _terminal_.
  */
 public fun <T, R> Sequence<Pair<T, R>>.unzip(): Pair<List<T>, List<R>> {
     val listT = ArrayList<T>()
@@ -532,7 +538,10 @@ private class GeneratorSequence<T: Any>(private val getInitialValue: () -> T?, p
 /**
  * Returns a wrapper sequence that provides values of this sequence, but ensures it can be iterated only one time.
  *
+ * The operation is _intermediate_ and _stateless_.
+ *
  * [IllegalStateException] is thrown on iterating the returned sequence from the second time.
+ *
  */
 public fun <T> Sequence<T>.constrainOnce(): Sequence<T> {
     // as? does not work in js