toMutableList documentation is vague #KT-35231

libraries/stdlib/common/src/generated/_Arrays.kt

@@ -8237,63 +8237,63 @@ public fun <C : MutableCollection<in Char>> CharArray.toCollection(destination:
 }
 
 /**
- * Returns a [HashSet] of all elements.
+ * Returns a new [HashSet] of all elements.
  */
 public fun <T> Array<out T>.toHashSet(): HashSet<T> {
     return toCollection(HashSet<T>(mapCapacity(size)))
 }
 
 /**
- * Returns a [HashSet] of all elements.
+ * Returns a new [HashSet] of all elements.
  */
 public fun ByteArray.toHashSet(): HashSet<Byte> {
     return toCollection(HashSet<Byte>(mapCapacity(size)))
 }
 
 /**
- * Returns a [HashSet] of all elements.
+ * Returns a new [HashSet] of all elements.
  */
 public fun ShortArray.toHashSet(): HashSet<Short> {
     return toCollection(HashSet<Short>(mapCapacity(size)))
 }
 
 /**
- * Returns a [HashSet] of all elements.
+ * Returns a new [HashSet] of all elements.
  */
 public fun IntArray.toHashSet(): HashSet<Int> {
     return toCollection(HashSet<Int>(mapCapacity(size)))
 }
 
 /**
- * Returns a [HashSet] of all elements.
+ * Returns a new [HashSet] of all elements.
  */
 public fun LongArray.toHashSet(): HashSet<Long> {
     return toCollection(HashSet<Long>(mapCapacity(size)))
 }
 
 /**
- * Returns a [HashSet] of all elements.
+ * Returns a new [HashSet] of all elements.
  */
 public fun FloatArray.toHashSet(): HashSet<Float> {
     return toCollection(HashSet<Float>(mapCapacity(size)))
 }
 
 /**
- * Returns a [HashSet] of all elements.
+ * Returns a new [HashSet] of all elements.
  */
 public fun DoubleArray.toHashSet(): HashSet<Double> {
     return toCollection(HashSet<Double>(mapCapacity(size)))
 }
 
 /**
- * Returns a [HashSet] of all elements.
+ * Returns a new [HashSet] of all elements.
  */
 public fun BooleanArray.toHashSet(): HashSet<Boolean> {
     return toCollection(HashSet<Boolean>(mapCapacity(size)))
 }
 
 /**
- * Returns a [HashSet] of all elements.
+ * Returns a new [HashSet] of all elements.
  */
 public fun CharArray.toHashSet(): HashSet<Char> {
     return toCollection(HashSet<Char>(mapCapacity(size)))
@@ -8399,14 +8399,14 @@ public fun CharArray.toList(): List<Char> {
 }
 
 /**
- * Returns a [MutableList] filled with all elements of this array.
+ * Returns a new [MutableList] filled with all elements of this array.
  */
 public fun <T> Array<out T>.toMutableList(): MutableList<T> {
     return ArrayList(this.asCollection())
 }
 
 /**
- * Returns a [MutableList] filled with all elements of this array.
+ * Returns a new [MutableList] filled with all elements of this array.
  */
 public fun ByteArray.toMutableList(): MutableList<Byte> {
     val list = ArrayList<Byte>(size)
@@ -8415,7 +8415,7 @@ public fun ByteArray.toMutableList(): MutableList<Byte> {
 }
 
 /**
- * Returns a [MutableList] filled with all elements of this array.
+ * Returns a new [MutableList] filled with all elements of this array.
  */
 public fun ShortArray.toMutableList(): MutableList<Short> {
     val list = ArrayList<Short>(size)
@@ -8424,7 +8424,7 @@ public fun ShortArray.toMutableList(): MutableList<Short> {
 }
 
 /**
- * Returns a [MutableList] filled with all elements of this array.
+ * Returns a new [MutableList] filled with all elements of this array.
  */
 public fun IntArray.toMutableList(): MutableList<Int> {
     val list = ArrayList<Int>(size)
@@ -8433,7 +8433,7 @@ public fun IntArray.toMutableList(): MutableList<Int> {
 }
 
 /**
- * Returns a [MutableList] filled with all elements of this array.
+ * Returns a new [MutableList] filled with all elements of this array.
  */
 public fun LongArray.toMutableList(): MutableList<Long> {
     val list = ArrayList<Long>(size)
@@ -8442,7 +8442,7 @@ public fun LongArray.toMutableList(): MutableList<Long> {
 }
 
 /**
- * Returns a [MutableList] filled with all elements of this array.
+ * Returns a new [MutableList] filled with all elements of this array.
  */
 public fun FloatArray.toMutableList(): MutableList<Float> {
     val list = ArrayList<Float>(size)
@@ -8451,7 +8451,7 @@ public fun FloatArray.toMutableList(): MutableList<Float> {
 }
 
 /**
- * Returns a [MutableList] filled with all elements of this array.
+ * Returns a new [MutableList] filled with all elements of this array.
  */
 public fun DoubleArray.toMutableList(): MutableList<Double> {
     val list = ArrayList<Double>(size)
@@ -8460,7 +8460,7 @@ public fun DoubleArray.toMutableList(): MutableList<Double> {
 }
 
 /**
- * Returns a [MutableList] filled with all elements of this array.
+ * Returns a new [MutableList] filled with all elements of this array.
  */
 public fun BooleanArray.toMutableList(): MutableList<Boolean> {
     val list = ArrayList<Boolean>(size)
@@ -8469,7 +8469,7 @@ public fun BooleanArray.toMutableList(): MutableList<Boolean> {
 }
 
 /**
- * Returns a [MutableList] filled with all elements of this array.
+ * Returns a new [MutableList] filled with all elements of this array.
  */
 public fun CharArray.toMutableList(): MutableList<Char> {
     val list = ArrayList<Char>(size)
@@ -10314,7 +10314,7 @@ public infix fun CharArray.subtract(other: Iterable<Char>): Set<Char> {
 }
 
 /**
- * Returns a mutable set containing all distinct elements from the given array.
+ * Returns a new [MutableSet] containing all distinct elements from the given array.
  * 
  * The returned set preserves the element iteration order of the original array.
  */
@@ -10325,7 +10325,7 @@ public fun <T> Array<out T>.toMutableSet(): MutableSet<T> {
 }
 
 /**
- * Returns a mutable set containing all distinct elements from the given array.
+ * Returns a new [MutableSet] containing all distinct elements from the given array.
  * 
  * The returned set preserves the element iteration order of the original array.
  */
@@ -10336,7 +10336,7 @@ public fun ByteArray.toMutableSet(): MutableSet<Byte> {
 }
 
 /**
- * Returns a mutable set containing all distinct elements from the given array.
+ * Returns a new [MutableSet] containing all distinct elements from the given array.
  * 
  * The returned set preserves the element iteration order of the original array.
  */
@@ -10347,7 +10347,7 @@ public fun ShortArray.toMutableSet(): MutableSet<Short> {
 }
 
 /**
- * Returns a mutable set containing all distinct elements from the given array.
+ * Returns a new [MutableSet] containing all distinct elements from the given array.
  * 
  * The returned set preserves the element iteration order of the original array.
  */
@@ -10358,7 +10358,7 @@ public fun IntArray.toMutableSet(): MutableSet<Int> {
 }
 
 /**
- * Returns a mutable set containing all distinct elements from the given array.
+ * Returns a new [MutableSet] containing all distinct elements from the given array.
  * 
  * The returned set preserves the element iteration order of the original array.
  */
@@ -10369,7 +10369,7 @@ public fun LongArray.toMutableSet(): MutableSet<Long> {
 }
 
 /**
- * Returns a mutable set containing all distinct elements from the given array.
+ * Returns a new [MutableSet] containing all distinct elements from the given array.
  * 
  * The returned set preserves the element iteration order of the original array.
  */
@@ -10380,7 +10380,7 @@ public fun FloatArray.toMutableSet(): MutableSet<Float> {
 }
 
 /**
- * Returns a mutable set containing all distinct elements from the given array.
+ * Returns a new [MutableSet] containing all distinct elements from the given array.
  * 
  * The returned set preserves the element iteration order of the original array.
  */
@@ -10391,7 +10391,7 @@ public fun DoubleArray.toMutableSet(): MutableSet<Double> {
 }
 
 /**
- * Returns a mutable set containing all distinct elements from the given array.
+ * Returns a new [MutableSet] containing all distinct elements from the given array.
  * 
  * The returned set preserves the element iteration order of the original array.
  */
@@ -10402,7 +10402,7 @@ public fun BooleanArray.toMutableSet(): MutableSet<Boolean> {
 }
 
 /**
- * Returns a mutable set containing all distinct elements from the given array.
+ * Returns a new [MutableSet] containing all distinct elements from the given array.
  * 
  * The returned set preserves the element iteration order of the original array.
  */

libraries/stdlib/common/src/generated/_Collections.kt

@@ -1204,7 +1204,7 @@ public fun <T, C : MutableCollection<in T>> Iterable<T>.toCollection(destination
 }
 
 /**
- * Returns a [HashSet] of all elements.
+ * Returns a new [HashSet] of all elements.
  */
 public fun <T> Iterable<T>.toHashSet(): HashSet<T> {
     return toCollection(HashSet<T>(mapCapacity(collectionSizeOrDefault(12))))
@@ -1225,7 +1225,7 @@ public fun <T> Iterable<T>.toList(): List<T> {
 }
 
 /**
- * Returns a [MutableList] filled with all elements of this collection.
+ * Returns a new [MutableList] filled with all elements of this collection.
  */
 public fun <T> Iterable<T>.toMutableList(): MutableList<T> {
     if (this is Collection<T>)
@@ -1234,7 +1234,7 @@ public fun <T> Iterable<T>.toMutableList(): MutableList<T> {
 }
 
 /**
- * Returns a [MutableList] filled with all elements of this collection.
+ * Returns a new [MutableList] filled with all elements of this collection.
  */
 public fun <T> Collection<T>.toMutableList(): MutableList<T> {
     return ArrayList(this)
@@ -1496,7 +1496,7 @@ public infix fun <T> Iterable<T>.subtract(other: Iterable<T>): Set<T> {
 }
 
 /**
- * Returns a mutable set containing all distinct elements from the given collection.
+ * Returns a new [MutableSet] containing all distinct elements from the given collection.
  * 
  * The returned set preserves the element iteration order of the original collection.
  */

libraries/stdlib/common/src/generated/_Sequences.kt

@@ -720,7 +720,7 @@ public fun <T, C : MutableCollection<in T>> Sequence<T>.toCollection(destination
 }
 
 /**
- * Returns a [HashSet] of all elements.
+ * Returns a new [HashSet] of all elements.
  *
  * The operation is _terminal_.
  */
@@ -738,7 +738,7 @@ public fun <T> Sequence<T>.toList(): List<T> {
 }
 
 /**
- * Returns a [MutableList] filled with all elements of this sequence.
+ * Returns a new [MutableList] filled with all elements of this sequence.
  *
  * The operation is _terminal_.
  */
@@ -1002,7 +1002,7 @@ public fun <T, K> Sequence<T>.distinctBy(selector: (T) -> K): Sequence<T> {
 }
 
 /**
- * Returns a mutable set containing all distinct elements from the given sequence.
+ * Returns a new [MutableSet] containing all distinct elements from the given sequence.
  * 
  * The returned set preserves the element iteration order of the original sequence.
  *

libraries/stdlib/common/src/generated/_Strings.kt

@@ -731,7 +731,7 @@ public fun <C : MutableCollection<in Char>> CharSequence.toCollection(destinatio
 }
 
 /**
- * Returns a [HashSet] of all characters.
+ * Returns a new [HashSet] of all characters.
  */
 public fun CharSequence.toHashSet(): HashSet<Char> {
     return toCollection(HashSet<Char>(mapCapacity(length)))
@@ -749,7 +749,7 @@ public fun CharSequence.toList(): List<Char> {
 }
 
 /**
- * Returns a [MutableList] filled with all characters of this char sequence.
+ * Returns a new [MutableList] filled with all characters of this char sequence.
  */
 public fun CharSequence.toMutableList(): MutableList<Char> {
     return toCollection(ArrayList<Char>(length))

libraries/stdlib/jvm/src/generated/_ArraysJvm.kt

@@ -2057,70 +2057,70 @@ public actual fun CharArray.toTypedArray(): Array<Char> {
 }
 
 /**
- * Returns a [SortedSet][java.util.SortedSet] of all elements.
+ * Returns a new [SortedSet][java.util.SortedSet] of all elements.
  */
 public fun <T : Comparable<T>> Array<out T>.toSortedSet(): java.util.SortedSet<T> {
     return toCollection(java.util.TreeSet<T>())
 }
 
 /**
- * Returns a [SortedSet][java.util.SortedSet] of all elements.
+ * Returns a new [SortedSet][java.util.SortedSet] of all elements.
  */
 public fun ByteArray.toSortedSet(): java.util.SortedSet<Byte> {
     return toCollection(java.util.TreeSet<Byte>())
 }
 
 /**
- * Returns a [SortedSet][java.util.SortedSet] of all elements.
+ * Returns a new [SortedSet][java.util.SortedSet] of all elements.
  */
 public fun ShortArray.toSortedSet(): java.util.SortedSet<Short> {
     return toCollection(java.util.TreeSet<Short>())
 }
 
 /**
- * Returns a [SortedSet][java.util.SortedSet] of all elements.
+ * Returns a new [SortedSet][java.util.SortedSet] of all elements.
  */
 public fun IntArray.toSortedSet(): java.util.SortedSet<Int> {
     return toCollection(java.util.TreeSet<Int>())
 }
 
 /**
- * Returns a [SortedSet][java.util.SortedSet] of all elements.
+ * Returns a new [SortedSet][java.util.SortedSet] of all elements.
  */
 public fun LongArray.toSortedSet(): java.util.SortedSet<Long> {
     return toCollection(java.util.TreeSet<Long>())
 }
 
 /**
- * Returns a [SortedSet][java.util.SortedSet] of all elements.
+ * Returns a new [SortedSet][java.util.SortedSet] of all elements.
  */
 public fun FloatArray.toSortedSet(): java.util.SortedSet<Float> {
     return toCollection(java.util.TreeSet<Float>())
 }
 
 /**
- * Returns a [SortedSet][java.util.SortedSet] of all elements.
+ * Returns a new [SortedSet][java.util.SortedSet] of all elements.
  */
 public fun DoubleArray.toSortedSet(): java.util.SortedSet<Double> {
     return toCollection(java.util.TreeSet<Double>())
 }
 
 /**
- * Returns a [SortedSet][java.util.SortedSet] of all elements.
+ * Returns a new [SortedSet][java.util.SortedSet] of all elements.
  */
 public fun BooleanArray.toSortedSet(): java.util.SortedSet<Boolean> {
     return toCollection(java.util.TreeSet<Boolean>())
 }
 
 /**
- * Returns a [SortedSet][java.util.SortedSet] of all elements.
+ * Returns a new [SortedSet][java.util.SortedSet] of all elements.
  */
 public fun CharArray.toSortedSet(): java.util.SortedSet<Char> {
     return toCollection(java.util.TreeSet<Char>())
 }
 
 /**
- * Returns a [SortedSet][java.util.SortedSet] of all elements.
+ * Returns a new [SortedSet][java.util.SortedSet] of all elements.
  * 
  * Elements in the set returned are sorted according to the given [comparator].
  */

libraries/stdlib/jvm/src/generated/_CollectionsJvm.kt

@@ -40,14 +40,14 @@ public actual fun <T> MutableList<T>.reverse(): Unit {
 }
 
 /**
- * Returns a [SortedSet][java.util.SortedSet] of all elements.
+ * Returns a new [SortedSet][java.util.SortedSet] of all elements.
  */
 public fun <T : Comparable<T>> Iterable<T>.toSortedSet(): java.util.SortedSet<T> {
     return toCollection(java.util.TreeSet<T>())
 }
 
 /**
- * Returns a [SortedSet][java.util.SortedSet] of all elements.
+ * Returns a new [SortedSet][java.util.SortedSet] of all elements.
  * 
  * Elements in the set returned are sorted according to the given [comparator].
  */

libraries/stdlib/jvm/src/generated/_SequencesJvm.kt

@@ -36,7 +36,7 @@ public fun <C : MutableCollection<in R>, R> Sequence<*>.filterIsInstanceTo(desti
 }
 
 /**
- * Returns a [SortedSet][java.util.SortedSet] of all elements.
+ * Returns a new [SortedSet][java.util.SortedSet] of all elements.
  *
  * The operation is _terminal_.
  */
@@ -45,7 +45,7 @@ public fun <T : Comparable<T>> Sequence<T>.toSortedSet(): java.util.SortedSet<T>
 }
 
 /**
- * Returns a [SortedSet][java.util.SortedSet] of all elements.
+ * Returns a new [SortedSet][java.util.SortedSet] of all elements.
  * 
  * Elements in the set returned are sorted according to the given [comparator].
  *

libraries/stdlib/jvm/src/generated/_StringsJvm.kt

@@ -25,7 +25,7 @@ public actual inline fun CharSequence.elementAt(index: Int): Char {
 }
 
 /**
- * Returns a [SortedSet][java.util.SortedSet] of all characters.
+ * Returns a new [SortedSet][java.util.SortedSet] of all characters.
  */
 public fun CharSequence.toSortedSet(): java.util.SortedSet<Char> {
     return toCollection(java.util.TreeSet<Char>())

libraries/tools/kotlin-stdlib-gen/src/templates/Sets.kt

@@ -19,7 +19,7 @@ object SetOps : TemplateGroupBase() {
     } builder {
         doc {
             """
-            Returns a mutable set containing all distinct ${f.element.pluralize()} from the given ${f.collection}.
+            Returns a new [MutableSet] containing all distinct ${f.element.pluralize()} from the given ${f.collection}.
 
             The returned set preserves the element iteration order of the original ${f.collection}.
             """

libraries/tools/kotlin-stdlib-gen/src/templates/Snapshots.kt

@@ -75,7 +75,7 @@ object Snapshots : TemplateGroupBase() {
         includeDefault()
         include(CharSequences)
     } builder {
-        doc { "Returns a [HashSet] of all ${f.element.pluralize()}." }
+        doc { "Returns a new [HashSet] of all ${f.element.pluralize()}." }
         returns("HashSet<T>")
         body { "return toCollection(HashSet<T>(mapCapacity(collectionSizeOrDefault(12))))" }
         body(Sequences) { "return toCollection(HashSet<T>())" }
@@ -89,7 +89,7 @@ object Snapshots : TemplateGroupBase() {
         platforms(Platform.JVM)
     } builder {
         typeParam("T : Comparable<T>")
-        doc { "Returns a [SortedSet][java.util.SortedSet] of all ${f.element.pluralize()}." }
+        doc { "Returns a new [SortedSet][java.util.SortedSet] of all ${f.element.pluralize()}." }
         returns("java.util.SortedSet<T>")
         body { "return toCollection(java.util.TreeSet<T>())" }
     }
@@ -100,7 +100,7 @@ object Snapshots : TemplateGroupBase() {
     } builder {
         doc {
             """
-                Returns a [SortedSet][java.util.SortedSet] of all ${f.element.pluralize()}.
+                Returns a new [SortedSet][java.util.SortedSet] of all ${f.element.pluralize()}.
 
                 Elements in the set returned are sorted according to the given [comparator].
             """
@@ -113,7 +113,7 @@ object Snapshots : TemplateGroupBase() {
         includeDefault()
         include(Collections, CharSequences)
     } builder {
-        doc { "Returns a [MutableList] filled with all ${f.element.pluralize()} of this ${f.collection}." }
+        doc { "Returns a new [MutableList] filled with all ${f.element.pluralize()} of this ${f.collection}." }
         returns("MutableList<T>")
         body { "return toCollection(ArrayList<T>())" }
         body(Iterables) {