From ea8529093907bdf910d88b3efd26c8e154bc06ca Mon Sep 17 00:00:00 2001
From: Ilya Gorbunov <ilya.gorbunov@jetbrains.com>
Date: Wed, 27 May 2015 21:47:38 +0300
Subject: [PATCH] Annotate deprecated members with proposed replacement.

---
 libraries/stdlib/src/generated/_Sequences.kt  | 52 +++++++++----------
 .../stdlib/src/kotlin/collections/Sequence.kt | 50 +++++++++++++-----
 .../src/kotlin/deprecated/Deprecated.kt       | 16 +++---
 .../stdlib/src/kotlin/text/StringsJVM.kt      | 20 +++----
 .../src/templates/Sequence.kt                 |  2 +
 5 files changed, 82 insertions(+), 58 deletions(-)

diff --git a/libraries/stdlib/src/generated/_Sequences.kt b/libraries/stdlib/src/generated/_Sequences.kt
index 2cd8cc72988..835eca74b85 100644
--- a/libraries/stdlib/src/generated/_Sequences.kt
+++ b/libraries/stdlib/src/generated/_Sequences.kt
@@ -161,7 +161,7 @@ public fun String.asSequence(): Sequence<Char> {
 /**
  * Returns a sequence from the given collection
  */
-deprecated("Use asSequence() instead")
+deprecated("Use asSequence() instead", ReplaceWith("asSequence()"))
 public fun <T> Array<out T>.sequence(): Sequence<T> {
     return asSequence()
 }
@@ -169,7 +169,7 @@ public fun <T> Array<out T>.sequence(): Sequence<T> {
 /**
  * Returns a sequence from the given collection
  */
-deprecated("Use asSequence() instead")
+deprecated("Use asSequence() instead", ReplaceWith("asSequence()"))
 public fun BooleanArray.sequence(): Sequence<Boolean> {
     return asSequence()
 }
@@ -177,7 +177,7 @@ public fun BooleanArray.sequence(): Sequence<Boolean> {
 /**
  * Returns a sequence from the given collection
  */
-deprecated("Use asSequence() instead")
+deprecated("Use asSequence() instead", ReplaceWith("asSequence()"))
 public fun ByteArray.sequence(): Sequence<Byte> {
     return asSequence()
 }
@@ -185,7 +185,7 @@ public fun ByteArray.sequence(): Sequence<Byte> {
 /**
  * Returns a sequence from the given collection
  */
-deprecated("Use asSequence() instead")
+deprecated("Use asSequence() instead", ReplaceWith("asSequence()"))
 public fun CharArray.sequence(): Sequence<Char> {
     return asSequence()
 }
@@ -193,7 +193,7 @@ public fun CharArray.sequence(): Sequence<Char> {
 /**
  * Returns a sequence from the given collection
  */
-deprecated("Use asSequence() instead")
+deprecated("Use asSequence() instead", ReplaceWith("asSequence()"))
 public fun DoubleArray.sequence(): Sequence<Double> {
     return asSequence()
 }
@@ -201,7 +201,7 @@ public fun DoubleArray.sequence(): Sequence<Double> {
 /**
  * Returns a sequence from the given collection
  */
-deprecated("Use asSequence() instead")
+deprecated("Use asSequence() instead", ReplaceWith("asSequence()"))
 public fun FloatArray.sequence(): Sequence<Float> {
     return asSequence()
 }
@@ -209,7 +209,7 @@ public fun FloatArray.sequence(): Sequence<Float> {
 /**
  * Returns a sequence from the given collection
  */
-deprecated("Use asSequence() instead")
+deprecated("Use asSequence() instead", ReplaceWith("asSequence()"))
 public fun IntArray.sequence(): Sequence<Int> {
     return asSequence()
 }
@@ -217,7 +217,7 @@ public fun IntArray.sequence(): Sequence<Int> {
 /**
  * Returns a sequence from the given collection
  */
-deprecated("Use asSequence() instead")
+deprecated("Use asSequence() instead", ReplaceWith("asSequence()"))
 public fun LongArray.sequence(): Sequence<Long> {
     return asSequence()
 }
@@ -225,7 +225,7 @@ public fun LongArray.sequence(): Sequence<Long> {
 /**
  * Returns a sequence from the given collection
  */
-deprecated("Use asSequence() instead")
+deprecated("Use asSequence() instead", ReplaceWith("asSequence()"))
 public fun ShortArray.sequence(): Sequence<Short> {
     return asSequence()
 }
@@ -233,7 +233,7 @@ public fun ShortArray.sequence(): Sequence<Short> {
 /**
  * Returns a sequence from the given collection
  */
-deprecated("Use asSequence() instead")
+deprecated("Use asSequence() instead", ReplaceWith("asSequence()"))
 public fun <T> Iterable<T>.sequence(): Sequence<T> {
     return asSequence()
 }
@@ -241,7 +241,7 @@ public fun <T> Iterable<T>.sequence(): Sequence<T> {
 /**
  * Returns a sequence from the given collection
  */
-deprecated("Use asSequence() instead")
+deprecated("Use asSequence() instead", ReplaceWith("asSequence()"))
 public fun <K, V> Map<K, V>.sequence(): Sequence<Map.Entry<K, V>> {
     return asSequence()
 }
@@ -249,7 +249,7 @@ public fun <K, V> Map<K, V>.sequence(): Sequence<Map.Entry<K, V>> {
 /**
  * Returns a sequence from the given collection
  */
-deprecated("Use asSequence() instead")
+deprecated("Use asSequence() instead", ReplaceWith("asSequence()"))
 public fun <T> Sequence<T>.sequence(): Sequence<T> {
     return this
 }
@@ -258,7 +258,7 @@ public fun <T> Sequence<T>.sequence(): Sequence<T> {
 /**
  * Returns a stream from the given collection
  */
-deprecated("Use asStream() instead")
+deprecated("Use asStream() instead", ReplaceWith("asStream()"))
 public fun <T> Stream<T>.stream(): Stream<T> {
     return this
 }
@@ -266,7 +266,7 @@ public fun <T> Stream<T>.stream(): Stream<T> {
 /**
  * Returns a sequence from the given collection
  */
-deprecated("Use asSequence() instead")
+deprecated("Use asSequence() instead", ReplaceWith("asSequence()"))
 public fun String.sequence(): Sequence<Char> {
     return asSequence()
 }
@@ -274,7 +274,7 @@ public fun String.sequence(): Sequence<Char> {
 /**
  * Returns a sequence from the given collection
  */
-deprecated("Use asSequence() instead")
+deprecated("Use asSequence() instead", ReplaceWith("asSequence()"))
 public fun <T> Array<out T>.stream(): Stream<T> {
     val sequence = asSequence()
     return object : Stream<T> {
@@ -287,7 +287,7 @@ public fun <T> Array<out T>.stream(): Stream<T> {
 /**
  * Returns a sequence from the given collection
  */
-deprecated("Use asSequence() instead")
+deprecated("Use asSequence() instead", ReplaceWith("asSequence()"))
 public fun BooleanArray.stream(): Stream<Boolean> {
     val sequence = asSequence()
     return object : Stream<Boolean> {
@@ -300,7 +300,7 @@ public fun BooleanArray.stream(): Stream<Boolean> {
 /**
  * Returns a sequence from the given collection
  */
-deprecated("Use asSequence() instead")
+deprecated("Use asSequence() instead", ReplaceWith("asSequence()"))
 public fun ByteArray.stream(): Stream<Byte> {
     val sequence = asSequence()
     return object : Stream<Byte> {
@@ -313,7 +313,7 @@ public fun ByteArray.stream(): Stream<Byte> {
 /**
  * Returns a sequence from the given collection
  */
-deprecated("Use asSequence() instead")
+deprecated("Use asSequence() instead", ReplaceWith("asSequence()"))
 public fun CharArray.stream(): Stream<Char> {
     val sequence = asSequence()
     return object : Stream<Char> {
@@ -326,7 +326,7 @@ public fun CharArray.stream(): Stream<Char> {
 /**
  * Returns a sequence from the given collection
  */
-deprecated("Use asSequence() instead")
+deprecated("Use asSequence() instead", ReplaceWith("asSequence()"))
 public fun DoubleArray.stream(): Stream<Double> {
     val sequence = asSequence()
     return object : Stream<Double> {
@@ -339,7 +339,7 @@ public fun DoubleArray.stream(): Stream<Double> {
 /**
  * Returns a sequence from the given collection
  */
-deprecated("Use asSequence() instead")
+deprecated("Use asSequence() instead", ReplaceWith("asSequence()"))
 public fun FloatArray.stream(): Stream<Float> {
     val sequence = asSequence()
     return object : Stream<Float> {
@@ -352,7 +352,7 @@ public fun FloatArray.stream(): Stream<Float> {
 /**
  * Returns a sequence from the given collection
  */
-deprecated("Use asSequence() instead")
+deprecated("Use asSequence() instead", ReplaceWith("asSequence()"))
 public fun IntArray.stream(): Stream<Int> {
     val sequence = asSequence()
     return object : Stream<Int> {
@@ -365,7 +365,7 @@ public fun IntArray.stream(): Stream<Int> {
 /**
  * Returns a sequence from the given collection
  */
-deprecated("Use asSequence() instead")
+deprecated("Use asSequence() instead", ReplaceWith("asSequence()"))
 public fun LongArray.stream(): Stream<Long> {
     val sequence = asSequence()
     return object : Stream<Long> {
@@ -378,7 +378,7 @@ public fun LongArray.stream(): Stream<Long> {
 /**
  * Returns a sequence from the given collection
  */
-deprecated("Use asSequence() instead")
+deprecated("Use asSequence() instead", ReplaceWith("asSequence()"))
 public fun ShortArray.stream(): Stream<Short> {
     val sequence = asSequence()
     return object : Stream<Short> {
@@ -391,7 +391,7 @@ public fun ShortArray.stream(): Stream<Short> {
 /**
  * Returns a sequence from the given collection
  */
-deprecated("Use asSequence() instead")
+deprecated("Use asSequence() instead", ReplaceWith("asSequence()"))
 public fun <T> Iterable<T>.stream(): Stream<T> {
     val sequence = asSequence()
     return object : Stream<T> {
@@ -404,7 +404,7 @@ public fun <T> Iterable<T>.stream(): Stream<T> {
 /**
  * Returns a sequence from the given collection
  */
-deprecated("Use asSequence() instead")
+deprecated("Use asSequence() instead", ReplaceWith("asSequence()"))
 public fun <K, V> Map<K, V>.stream(): Stream<Map.Entry<K, V>> {
     val sequence = asSequence()
     return object : Stream<Map.Entry<K, V>> {
@@ -417,7 +417,7 @@ public fun <K, V> Map<K, V>.stream(): Stream<Map.Entry<K, V>> {
 /**
  * Returns a sequence from the given collection
  */
-deprecated("Use asSequence() instead")
+deprecated("Use asSequence() instead", ReplaceWith("asSequence()"))
 public fun String.stream(): Stream<Char> {
     val sequence = asSequence()
     return object : Stream<Char> {
diff --git a/libraries/stdlib/src/kotlin/collections/Sequence.kt b/libraries/stdlib/src/kotlin/collections/Sequence.kt
index 51a651e2e5b..7d9a1d1a6db 100644
--- a/libraries/stdlib/src/kotlin/collections/Sequence.kt
+++ b/libraries/stdlib/src/kotlin/collections/Sequence.kt
@@ -23,10 +23,10 @@ public fun<T> Stream<T>.toSequence(): Sequence<T> = object : Sequence<T> {
     override fun iterator(): Iterator<T> = this@toSequence.iterator()
 }
 
-deprecated("Use sequenceOf() instead")
+deprecated("Use sequenceOf() instead", ReplaceWith("sequenceOf(*elements)"))
 public fun <T> streamOf(vararg elements: T): Stream<T> = elements.stream()
 
-deprecated("Use sequenceOf() instead")
+deprecated("Use sequenceOf() instead", ReplaceWith("sequenceOf(progression)"))
 public fun <T> streamOf(progression: Progression<T>): Stream<T> = object : Stream<T> {
     override fun iterator(): Iterator<T> = progression.iterator()
 }
@@ -48,7 +48,7 @@ public fun <T> Iterator<T>.sequence(): Sequence<T> = asSequence()
 /**
  * Creates a sequence that returns all values from this enumeration. The sequence is constrained to be iterated only once.
  */
-public fun<T> Enumeration<T>.asSequence(): Sequence<T> = this.iterator().sequence()
+public fun<T> Enumeration<T>.asSequence(): Sequence<T> = this.iterator().asSequence()
 
 /**
  * Creates a sequence that returns the specified values.
@@ -133,7 +133,9 @@ public class TransformingStream<T, R>(stream: Stream<T>, transformer: (T) -> R)
  * in the underlying [sequence].
  */
 deprecated("This class is an implementation detail and shall be made internal soon. Use sequence.map() instead.")
-public class TransformingSequence<T, R>(private val sequence: Sequence<T>, private val transformer: (T) -> R) : Sequence<R> {
+public class TransformingSequence<T, R>
+deprecated("This class is an implementation detail and shall be made internal soon.", ReplaceWith("sequence.map(transformer)"))
+(private val sequence: Sequence<T>, private val transformer: (T) -> R) : Sequence<R> {
     override fun iterator(): Iterator<R> = object : Iterator<R> {
         val iterator = sequence.iterator()
         override fun next(): R {
@@ -156,7 +158,9 @@ public class TransformingIndexedStream<T, R>(stream: Stream<T>, transformer: (In
  * sequence along with the value itself.
  */
 deprecated("This class is an implementation detail and shall be made internal soon. Use sequence.mapIndexed() instead.")
-public class TransformingIndexedSequence<T, R>(private val sequence: Sequence<T>, private val transformer: (Int, T) -> R) : Sequence<R> {
+public class TransformingIndexedSequence<T, R>
+deprecated("This class is an implementation detail and shall be made internal soon.", ReplaceWith("sequence.mapIndexed(transformer)"))
+(private val sequence: Sequence<T>, private val transformer: (Int, T) -> R) : Sequence<R> {
     override fun iterator(): Iterator<R> = object : Iterator<R> {
         val iterator = sequence.iterator()
         var index = 0
@@ -179,7 +183,9 @@ public class IndexingStream<T>(stream: Stream<T>)
  * [IndexedValue] objects.
  */
 deprecated("This class is an implementation detail and shall be made internal soon. Use sequence.withIndex() instead.")
-public class IndexingSequence<T>(private val sequence: Sequence<T>) : Sequence<IndexedValue<T>> {
+public class IndexingSequence<T>
+deprecated("This class is an implementation detail and shall be made internal soon.", ReplaceWith("sequence.withIndex()"))
+(private val sequence: Sequence<T>) : Sequence<IndexedValue<T>> {
     override fun iterator(): Iterator<IndexedValue<T>> = object : Iterator<IndexedValue<T>> {
         val iterator = sequence.iterator()
         var index = 0
@@ -203,7 +209,9 @@ public class MergingStream<T1, T2, V>(stream1: Stream<T1>, stream2: Stream<T2>,
  * values as soon as one of the underlying sequences stops returning values.
  */
 deprecated("This class is an implementation detail and shall be made internal soon. Use sequence.merge() instead.")
-public class MergingSequence<T1, T2, V>(private val sequence1: Sequence<T1>,
+public class MergingSequence<T1, T2, V>
+deprecated("This class is an implementation detail and shall be made internal soon.", ReplaceWith("sequence1.merge(sequence2, transform)"))
+                                       (private val sequence1: Sequence<T1>,
                                         private val sequence2: Sequence<T2>,
                                         private val transform: (T1, T2) -> V
                                        ) : Sequence<V> {
@@ -225,7 +233,9 @@ public class FlatteningStream<T, R>(stream: Stream<T>, transformer: (T) -> Strea
 : Stream<R> by FlatteningSequence(stream.toSequence(), { transformer(it).toSequence() })
 
 deprecated("This class is an implementation detail and shall be made internal soon. Use sequence.flatMap() instead.")
-public class FlatteningSequence<T, R>(private val sequence: Sequence<T>,
+public class FlatteningSequence<T, R>
+deprecated("This class is an implementation detail and shall be made internal soon.", ReplaceWith("sequence.flatMap(transformer)"))
+                                     (private val sequence: Sequence<T>,
                                       private val transformer: (T) -> Sequence<R>
                                      ) : Sequence<R> {
     override fun iterator(): Iterator<R> = object : Iterator<R> {
@@ -268,7 +278,9 @@ public class Multistream<T>(stream: Stream<Stream<T>>)
 : Stream<T> by FlatteningSequence(stream.toSequence(), { it.toSequence() })
 
 deprecated("This class is an implementation detail and shall be made internal soon. Use sequence.flatten() instead.")
-public class MultiSequence<T>(private val sequence: Sequence<Sequence<T>>) : Sequence<T> {
+public class MultiSequence<T>
+deprecated("This class is an implementation detail and shall be made internal soon.", ReplaceWith("sequence.flatten()"))
+(private val sequence: Sequence<Sequence<T>>) : Sequence<T> {
     override fun iterator(): Iterator<T> = object : Iterator<T> {
         val iterator = sequence.iterator()
         var itemIterator: Iterator<T>? = null
@@ -313,7 +325,9 @@ public class TakeStream<T>(stream: Stream<T>, count: Int)
  * as soon as that count is reached.
  */
 deprecated("This class is an implementation detail and shall be made internal soon. Use sequence.take() instead.")
-public class TakeSequence<T>(private val sequence: Sequence<T>,
+public class TakeSequence<T>
+deprecated("This class is an implementation detail and shall be made internal soon.", ReplaceWith("sequence.take(count)"))
+                            (private val sequence: Sequence<T>,
                              private val count: Int
                             ) : Sequence<T> {
     init {
@@ -345,7 +359,9 @@ public class TakeWhileStream<T>(stream: Stream<T>, predicate: (T) -> Boolean) :
  * `true`, and stops returning values once the function returns `false` for the next element.
  */
 deprecated("This class is an implementation detail and shall be made internal soon. Use sequence.takeWhile() instead.")
-public class TakeWhileSequence<T>(private val sequence: Sequence<T>,
+public class TakeWhileSequence<T>
+deprecated("This class is an implementation detail and shall be made internal soon.", ReplaceWith("sequence.takeWhile(predicate)"))
+                                 (private val sequence: Sequence<T>,
                                   private val predicate: (T) -> Boolean
                                  ) : Sequence<T> {
     override fun iterator(): Iterator<T> = object : Iterator<T> {
@@ -395,7 +411,9 @@ public class DropStream<T>(stream: Stream<T>, count: Int)
  * all values after that.
  */
 deprecated("This class is an implementation detail and shall be made internal soon. Use sequence.drop() instead.")
-public class DropSequence<T>(private val sequence: Sequence<T>,
+public class DropSequence<T>
+deprecated("This class is an implementation detail and shall be made internal soon.", ReplaceWith("sequence.drop(count)"))
+                            (private val sequence: Sequence<T>,
                              private val count: Int
                             ) : Sequence<T> {
     init {
@@ -434,7 +452,9 @@ public class DropWhileStream<T>(stream: Stream<T>, predicate: (T) -> Boolean) :
  * all values after that.
  */
 deprecated("This class is an implementation detail and shall be made internal soon. Use sequence.dropWhile() instead.")
-public class DropWhileSequence<T>(private val sequence: Sequence<T>,
+public class DropWhileSequence<T>
+deprecated("This class is an implementation detail and shall be made internal soon.", ReplaceWith("sequence.dropWhile(predicate)"))
+                                 (private val sequence: Sequence<T>,
                                   private val predicate: (T) -> Boolean
                                  ) : Sequence<T> {
 
@@ -507,7 +527,9 @@ private class DistinctIterator<T, K>(private val source : Iterator<T>, private v
  * `null` is returned from [producer].
  */
 deprecated("This class is an implementation detail and shall be made internal soon. Use function sequence(nextFunction: () -> T?) instead.")
-public class FunctionSequence<T : Any>(private val producer: () -> T?) : Sequence<T> {
+public class FunctionSequence<T : Any>
+deprecated("This class is an implementation detail and shall be made internal soon.", ReplaceWith("sequence(producer)"))
+(private val producer: () -> T?) : Sequence<T> {
     override fun iterator(): Iterator<T> = object : Iterator<T> {
         var nextState: Int = -1 // -1 for unknown, 0 for done, 1 for continue
         var nextItem: T? = null
diff --git a/libraries/stdlib/src/kotlin/deprecated/Deprecated.kt b/libraries/stdlib/src/kotlin/deprecated/Deprecated.kt
index 4b048dcb5a4..2bfaf07990e 100644
--- a/libraries/stdlib/src/kotlin/deprecated/Deprecated.kt
+++ b/libraries/stdlib/src/kotlin/deprecated/Deprecated.kt
@@ -8,23 +8,23 @@ public inline fun <T> Array<out T>.find(predicate: (T) -> Boolean): T? = firstOr
 deprecated("Use firstOrNull function instead.", ReplaceWith("firstOrNull(predicate)"))
 public inline fun <T> Iterable<T>.find(predicate: (T) -> Boolean): T? = firstOrNull(predicate)
 
-deprecated("Use listOf(...) or arrayListOf(...) instead")
+deprecated("Use listOf(...) or arrayListOf(...) instead", ReplaceWith("arrayListOf(*values)"))
 public fun arrayList<T>(vararg values: T): ArrayList<T> = arrayListOf(*values)
 
-deprecated("Use setOf(...) or hashSetOf(...) instead")
+deprecated("Use setOf(...) or hashSetOf(...) instead", ReplaceWith("hashSetOf(*values)"))
 public fun hashSet<T>(vararg values: T): HashSet<T> = hashSetOf(*values)
 
-deprecated("Use mapOf(...) or hashMapOf(...) instead")
+deprecated("Use mapOf(...) or hashMapOf(...) instead", ReplaceWith("hashMapOf(*values)"))
 public fun <K, V> hashMap(vararg values: Pair<K, V>): HashMap<K, V> = hashMapOf(*values)
 
-deprecated("Use listOf(...) or linkedListOf(...) instead")
+deprecated("Use listOf(...) or linkedListOf(...) instead", ReplaceWith("linkedListOf(*values)"))
 public fun linkedList<T>(vararg values: T): LinkedList<T> = linkedListOf(*values)
 
 deprecated("Use linkedMapOf(...) instead", ReplaceWith("linkedMapOf(*values)"))
 public fun <K, V> linkedMap(vararg values: Pair<K, V>): LinkedHashMap<K, V> = linkedMapOf(*values)
 
 /** Copies all characters into a [[Collection] */
-deprecated("Use toList() instead.")
+deprecated("Use toList() instead.", ReplaceWith("toList()"))
 public fun String.toCollection(): Collection<Char> = toCollection(ArrayList<Char>(this.length()))
 
 /**
@@ -32,7 +32,7 @@ public fun String.toCollection(): Collection<Char> = toCollection(ArrayList<Char
  *
  * @includeFunctionBody ../../test/text/StringTest.kt find
  */
-deprecated("Use firstOrNull instead")
+deprecated("Use firstOrNull instead", ReplaceWith("firstOrNull(predicate)"))
 public inline fun String.find(predicate: (Char) -> Boolean): Char? {
     for (c in this) if (predicate(c)) return c
     return null
@@ -43,7 +43,7 @@ public inline fun String.find(predicate: (Char) -> Boolean): Char? {
  *
  * @includeFunctionBody ../../test/text/StringTest.kt findNot
  */
-deprecated("Use firstOrNull instead")
+deprecated("Use firstOrNull instead with negated predicate")
 public inline fun String.findNot(predicate: (Char) -> Boolean): Char? {
     for (c in this) if (!predicate(c)) return c
     return null
@@ -122,7 +122,7 @@ public val <T> List<T>.first: T?
  *
  * @includeFunctionBody ../../test/collections/ListSpecificTest.kt last
  */
-deprecated("Use lastOrNull() function instead")
+deprecated("Use lastOrNull() function instead", ReplaceWith("this.lastOrNull()"))
 public val <T> List<T>.last: T?
     get() {
         val s = this.size()
diff --git a/libraries/stdlib/src/kotlin/text/StringsJVM.kt b/libraries/stdlib/src/kotlin/text/StringsJVM.kt
index 9dd5e9d0b84..030c12497b4 100644
--- a/libraries/stdlib/src/kotlin/text/StringsJVM.kt
+++ b/libraries/stdlib/src/kotlin/text/StringsJVM.kt
@@ -87,7 +87,7 @@ public fun String.replaceFirstLiteral(oldValue: String, newValue: String, ignore
  * Returns a new string obtained by replacing each substring of this string that matches the given regular expression
  * with the given [replacement].
  */
-deprecated("Use String.replace(Regex, String) instead. You can convert regex parameter with .toRegex() extension function.")
+deprecated("Use String.replace(Regex, String) instead. You can convert regex parameter with .toRegex() extension function.", ReplaceWith("replace(regex.toRegex(), replacement)"))
 public fun String.replaceAll(regex: String, replacement: String): String = (this as java.lang.String).replaceAll(regex, replacement)
 
 /**
@@ -130,13 +130,13 @@ public fun String.split(regex: Pattern, limit: Int = 0): List<String>
 /**
  * Splits this string around matches of the given regular expression.
  */
-deprecated("Convert String argument to regex with toRegex or use splitBy instead.")
+deprecated("Convert String argument to regex with toRegex or use splitBy instead. Please note the change of return type and empty elements handling.")
 public fun String.split(regex: String): Array<String> = (this as java.lang.String).split(regex)
 
 /**
  * Splits this string into at most [limit] chunks around matches of the given regular expression.
  */
-deprecated("Convert String argument to regex with toRegex or use splitBy instead.")
+deprecated("Convert String argument to regex with toRegex or use splitBy instead. Please note the change of return type and limit parameter restrictions.")
 public fun String.split(regex: String, limit: Int): Array<String> = (this as java.lang.String).split(regex, limit)
 
 /**
@@ -259,7 +259,7 @@ public fun String(stringBuilder: java.lang.StringBuilder): String = java.lang.St
 /**
  * Replaces the first substring of this string that matches the given regular expression with the given replacement.
  */
-deprecated("Use replaceFirst(Regex, String) or replaceFirstLiteral(String, String) instead.")
+deprecated("Use replaceFirst(Regex, String) or replaceFirstLiteral(String, String) instead.", ReplaceWith("replaceFirst(regex.toRegex(), replacement)"))
 public fun String.replaceFirst(regex: String, replacement: String): String = (this as java.lang.String).replaceFirst(regex, replacement)
 
 /**
@@ -280,7 +280,7 @@ public fun String.codePointCount(beginIndex: Int, endIndex: Int): Int = (this as
 /**
  * Compares two strings lexicographically, ignoring case differences.
  */
-deprecated("Use compareTo with true passed to ignoreCase parameter.")
+deprecated("Use compareTo with true passed to ignoreCase parameter.", ReplaceWith("compareTo(str, ignoreCase = true)"))
 public fun String.compareToIgnoreCase(str: String): Int = (this as java.lang.String).compareToIgnoreCase(str)
 
 /**
@@ -331,7 +331,7 @@ public fun String.isBlank(): Boolean = length() == 0 || all { it.isWhitespace()
 /**
  * Returns `true` if this string matches the given regular expression.
  */
-deprecated("Use String.matches(Regex) instead. You can convert regex parameter with .toRegex() extension function.")
+deprecated("Use String.matches(Regex) instead. You can convert regex parameter with .toRegex() extension function.", ReplaceWith("matches(regex.toRegex())"))
 public fun String.matches(regex: String): Boolean = (this as java.lang.String).matches(regex)
 
 /**
@@ -347,7 +347,7 @@ public fun String.offsetByCodePoints(index: Int, codePointOffset: Int): Int = (t
  * @param ooffset the start offset in the other string of the substring to compare.
  * @param len the length of the substring to compare.
  */
-deprecated("Use regionMatches overload with ignoreCase as optional last parameter.")
+deprecated("Use regionMatches overload with ignoreCase as optional last parameter.", ReplaceWith("regionMatches(toffset, other, ooffset, len, ignoreCase)"))
 public fun String.regionMatches(ignoreCase: Boolean, toffset: Int, other: String, ooffset: Int, len: Int): Boolean = (this as java.lang.String).regionMatches(ignoreCase, toffset, other, ooffset, len)
 
 /**
@@ -431,13 +431,13 @@ public fun String.toByteArray(charset: String): ByteArray = (this as java.lang.S
  */
 public fun String.toByteArray(charset: Charset = Charsets.UTF_8): ByteArray = (this as java.lang.String).getBytes(charset)
 
-deprecated("Use toByteArray() instead to emphasize copy behaviour")
+deprecated("Use toByteArray() instead to emphasize copy behaviour", ReplaceWith("toByteArray()"))
 public fun String.getBytes(): ByteArray = (this as java.lang.String).getBytes()
 
-deprecated("Use toByteArray(charset) instead to emphasize copy behaviour")
+deprecated("Use toByteArray(charset) instead to emphasize copy behaviour", ReplaceWith("toByteArray(charset)"))
 public fun String.getBytes(charset: Charset): ByteArray = (this as java.lang.String).getBytes(charset)
 
-deprecated("Use toByteArray(charset) instead to emphasize copy behaviour")
+deprecated("Use toByteArray(charset) instead to emphasize copy behaviour", ReplaceWith("toByteArray(charset)"))
 public fun String.getBytes(charset: String): ByteArray = (this as java.lang.String).getBytes(charset)
 
 /**
diff --git a/libraries/tools/kotlin-stdlib-gen/src/templates/Sequence.kt b/libraries/tools/kotlin-stdlib-gen/src/templates/Sequence.kt
index 480175ea5f3..3d26075baf4 100644
--- a/libraries/tools/kotlin-stdlib-gen/src/templates/Sequence.kt
+++ b/libraries/tools/kotlin-stdlib-gen/src/templates/Sequence.kt
@@ -10,6 +10,7 @@ fun sequences(): List<GenericFunction> {
         exclude(Sequences)
         deprecate { "Use asSequence() instead" }
         doc { "Returns a sequence from the given collection" }
+        deprecateReplacement { "asSequence()" }
         returns("Stream<T>")
         body {
             """
@@ -28,6 +29,7 @@ fun sequences(): List<GenericFunction> {
         include(Maps)
         exclude(Sequences)
         deprecate { "Use asSequence() instead" }
+        deprecateReplacement { "asSequence()" }
         doc { "Returns a sequence from the given collection" }
         returns("Sequence<T>")
         body {