Docs and samples for 'pairwise' function

libraries/stdlib/src/generated/_Collections.kt

@@ -1854,11 +1854,26 @@ public inline fun <T> Iterable<T>.minusElement(element: T): List<T> {
     return minus(element)
 }
 
+/**
+ * Returns a list of pairs of each two adjacent elements in this collection.
+ * 
+ * The returned list is empty if this collection contains less than two elements.
+ * 
+ * @sample samples.collections.Collections.Transformations.pairwise
+ */
 @SinceKotlin("1.2")
 public fun <T> Iterable<T>.pairwise(): List<Pair<T, T>> {
     return pairwise { a, b -> a to b }
 }
 
+/**
+ * Returns a list containing the results of applying the given [transform] function
+ * to an each pair of two adjacent elements in this collection.
+ * 
+ * The returned list is empty if this collection contains less than two elements.
+ * 
+ * @sample samples.collections.Collections.Transformations.pairwiseToFindDeltas
+ */
 @SinceKotlin("1.2")
 public inline fun <T, R> Iterable<T>.pairwise(transform: (a: T, b: T) -> R): List<R> {
     val iterator = iterator()

libraries/stdlib/src/generated/_Sequences.kt

@@ -1423,11 +1423,30 @@ public inline fun <T> Sequence<T>.minusElement(element: T): Sequence<T> {
     return minus(element)
 }
 
+/**
+ * Returns a sequence of pairs of each two adjacent elements in this sequence.
+ * 
+ * The returned sequence is empty if this sequence contains less than two elements.
+ * 
+ * @sample samples.collections.Collections.Transformations.pairwise
+ *
+ * The operation is _intermediate_ and _stateless_.
+ */
 @SinceKotlin("1.2")
 public fun <T> Sequence<T>.pairwise(): Sequence<Pair<T, T>> {
     return pairwise { a, b -> a to b }
 }
 
+/**
+ * Returns a sequence containing the results of applying the given [transform] function
+ * to an each pair of two adjacent elements in this sequence.
+ * 
+ * The returned sequence is empty if this sequence contains less than two elements.
+ * 
+ * @sample samples.collections.Collections.Transformations.pairwiseToFindDeltas
+ *
+ * The operation is _intermediate_ and _stateless_.
+ */
 @SinceKotlin("1.2")
 public fun <T, R> Sequence<T>.pairwise(transform: (a: T, b: T) -> R): Sequence<R> {
     return buildSequence result@ {

libraries/stdlib/src/generated/_Strings.kt

@@ -1130,11 +1130,26 @@ public fun <R> CharSequence.chunkedSequence(size: Int, transform: (CharSequence)
     return windowedSequence(size, size, transform)
 }
 
+/**
+ * Returns a list of pairs of each two adjacent characters in this char sequence.
+ * 
+ * The returned list is empty if this char sequence contains less than two characters.
+ * 
+ * @sample samples.collections.Collections.Transformations.pairwise
+ */
 @SinceKotlin("1.2")
 public fun CharSequence.pairwise(): List<Pair<Char, Char>> {
     return pairwise { a, b -> a to b }
 }
 
+/**
+ * Returns a list containing the results of applying the given [transform] function
+ * to an each pair of two adjacent characters in this char sequence.
+ * 
+ * The returned list is empty if this char sequence contains less than two characters.
+ * 
+ * @sample samples.collections.Collections.Transformations.pairwiseToFindDeltas
+ */
 @SinceKotlin("1.2")
 public inline fun <R> CharSequence.pairwise(transform: (a: Char, b: Char) -> R): List<R> {
     val size = length - 1