diff --git a/libraries/stdlib/src/generated/ArraysFromJavaCollections.kt b/libraries/stdlib/src/generated/ArraysFromJavaCollections.kt
index 73164eda710..5d72ce73c9f 100644
--- a/libraries/stdlib/src/generated/ArraysFromJavaCollections.kt
+++ b/libraries/stdlib/src/generated/ArraysFromJavaCollections.kt
@@ -1,8 +1,15 @@
-// NOTE this file is auto-generated from stdlib/src/kotlin/JavaCollections.kt
+// NOTE this file is auto-generated from src/kotlin/JavaCollections.kt
 package kotlin
 
 import java.util.*
 
+//
+// This file contains methods which are optimised for working on Collection / Array collections where the size
+// could be used to implement a more optimal solution
+//
+// See [[GenerateStandardLib.kt]] for more details
+//
+
 /**
  * Returns a new List containing the results of applying the given function to each element in this collection
  *
diff --git a/libraries/stdlib/src/generated/ArraysFromJavaIterables.kt b/libraries/stdlib/src/generated/ArraysFromJavaIterables.kt
index 2101835b937..40cfd14f442 100644
--- a/libraries/stdlib/src/generated/ArraysFromJavaIterables.kt
+++ b/libraries/stdlib/src/generated/ArraysFromJavaIterables.kt
@@ -1,4 +1,4 @@
-// NOTE this file is auto-generated from stdlib/src/kotlin/JavaIterables.kt
+// NOTE this file is auto-generated from src/kotlin/JavaIterables.kt
 package kotlin
 
 import kotlin.util.*
diff --git a/libraries/stdlib/src/generated/ArraysFromJavaIterablesLazy.kt b/libraries/stdlib/src/generated/ArraysFromJavaIterablesLazy.kt
index 93beef96ced..63b3fefa7fd 100644
--- a/libraries/stdlib/src/generated/ArraysFromJavaIterablesLazy.kt
+++ b/libraries/stdlib/src/generated/ArraysFromJavaIterablesLazy.kt
@@ -1,4 +1,4 @@
-// NOTE this file is auto-generated from stdlib/src/kotlin/JavaIterablesLazy.kt
+// NOTE this file is auto-generated from src/kotlin/JavaIterablesLazy.kt
 package kotlin
 
 import kotlin.util.*
@@ -67,7 +67,7 @@ inline fun <T> Array<T>.takeWhile(predicate: (T) -> Boolean): List<T> = takeWhil
  *
  * @includeFunction ../../test/CollectionTest.kt join
  */
-inline fun <T> Array<T>.join(separator: String, prefix: String = "", postfix: String = "") : String {
+inline fun <T> Array<T>.join(separator: String = ", ", prefix: String = "", postfix: String = "") : String {
     val buffer = StringBuilder(prefix)
     var first = true
     for (element in this) {
diff --git a/libraries/stdlib/src/generated/JavaUtilIterablesFromJavaCollections.kt b/libraries/stdlib/src/generated/JavaUtilIterablesFromJavaCollections.kt
index 3b7340d86fe..0ab7e3e1d8e 100644
--- a/libraries/stdlib/src/generated/JavaUtilIterablesFromJavaCollections.kt
+++ b/libraries/stdlib/src/generated/JavaUtilIterablesFromJavaCollections.kt
@@ -1,8 +1,15 @@
-// NOTE this file is auto-generated from stdlib/src/kotlin/JavaCollections.kt
+// NOTE this file is auto-generated from src/kotlin/JavaCollections.kt
 package kotlin
 
 import java.util.*
 
+//
+// This file contains methods which are optimised for working on Collection / Array collections where the size
+// could be used to implement a more optimal solution
+//
+// See [[GenerateStandardLib.kt]] for more details
+//
+
 /**
  * Returns a new List containing the results of applying the given function to each element in this collection
  *
diff --git a/libraries/stdlib/src/generated/JavaUtilIteratorsFromJavaIterables.kt b/libraries/stdlib/src/generated/JavaUtilIteratorsFromJavaIterables.kt
index 59cadc718e9..8500b4eb6b3 100644
--- a/libraries/stdlib/src/generated/JavaUtilIteratorsFromJavaIterables.kt
+++ b/libraries/stdlib/src/generated/JavaUtilIteratorsFromJavaIterables.kt
@@ -1,4 +1,4 @@
-// NOTE this file is auto-generated from stdlib/src/kotlin/JavaIterables.kt
+// NOTE this file is auto-generated from src/kotlin/JavaIterables.kt
 package kotlin
 
 import java.util.*
diff --git a/libraries/stdlib/src/generated/StandardFromJavaCollections.kt b/libraries/stdlib/src/generated/StandardFromJavaCollections.kt
index 9a223d47b6d..685fe9ffc2b 100644
--- a/libraries/stdlib/src/generated/StandardFromJavaCollections.kt
+++ b/libraries/stdlib/src/generated/StandardFromJavaCollections.kt
@@ -1,8 +1,15 @@
-// NOTE this file is auto-generated from stdlib/src/kotlin/JavaCollections.kt
+// NOTE this file is auto-generated from src/kotlin/JavaCollections.kt
 package kotlin
 
 import java.util.*
 
+//
+// This file contains methods which are optimised for working on Collection / Array collections where the size
+// could be used to implement a more optimal solution
+//
+// See [[GenerateStandardLib.kt]] for more details
+//
+
 /**
  * Returns a new List containing the results of applying the given function to each element in this collection
  *
diff --git a/libraries/stdlib/src/generated/StandardFromJavaIterables.kt b/libraries/stdlib/src/generated/StandardFromJavaIterables.kt
index 7c8461d1bcc..9202070b625 100644
--- a/libraries/stdlib/src/generated/StandardFromJavaIterables.kt
+++ b/libraries/stdlib/src/generated/StandardFromJavaIterables.kt
@@ -1,4 +1,4 @@
-// NOTE this file is auto-generated from stdlib/src/kotlin/JavaIterables.kt
+// NOTE this file is auto-generated from src/kotlin/JavaIterables.kt
 package kotlin
 
 import kotlin.util.*
diff --git a/libraries/stdlib/src/generated/StandardFromJavaIterablesLazy.kt b/libraries/stdlib/src/generated/StandardFromJavaIterablesLazy.kt
index 5313030e060..37f635e52bb 100644
--- a/libraries/stdlib/src/generated/StandardFromJavaIterablesLazy.kt
+++ b/libraries/stdlib/src/generated/StandardFromJavaIterablesLazy.kt
@@ -1,4 +1,4 @@
-// NOTE this file is auto-generated from stdlib/src/kotlin/JavaIterablesLazy.kt
+// NOTE this file is auto-generated from src/kotlin/JavaIterablesLazy.kt
 package kotlin
 
 import kotlin.util.*
@@ -67,7 +67,7 @@ inline fun <T> Iterable<T>.takeWhile(predicate: (T) -> Boolean): List<T> = takeW
  *
  * @includeFunction ../../test/CollectionTest.kt join
  */
-inline fun <T> Iterable<T>.join(separator: String, prefix: String = "", postfix: String = "") : String {
+inline fun <T> Iterable<T>.join(separator: String = ", ", prefix: String = "", postfix: String = "") : String {
     val buffer = StringBuilder(prefix)
     var first = true
     for (element in this) {
diff --git a/libraries/stdlib/src/kotlin/Iterators.kt b/libraries/stdlib/src/kotlin/Iterators.kt
index 9074972a0f8..18ba2bcc719 100644
--- a/libraries/stdlib/src/kotlin/Iterators.kt
+++ b/libraries/stdlib/src/kotlin/Iterators.kt
@@ -129,20 +129,13 @@ private class TakeWhileIterator<T>(val iterator: java.util.Iterator<T>, val pred
  *
  * @includeFunction ../../test/iterators/IteratorsTest.kt joinConcatenatesTheFirstNElementsAboveAThreshold
  */
-inline fun <T> java.util.Iterator<T>.join(separator: String, prefix: String = "", postfix: String = "", limit: Int = 20) : String {
+inline fun <T> java.util.Iterator<T>.join(separator: String = ", ", prefix: String = "", postfix: String = "", limit: Int? = null) : String {
     val buffer = StringBuilder(prefix)
     var first = true; var count = 0
     for (element in this) {
         if (first) first = false else buffer.append(separator)
-        if (++count <= limit) buffer.append(element) else break
+        if (limit == null || ++count <= limit) buffer.append(element) else break
     }
-    if (count > limit) buffer.append("...")
+    if (limit != null && count > limit) buffer.append("...")
     return buffer.append(postfix).toString().sure()
 }
-
-/**
- * Returns a comma-separated representation of no more than the first 10 elements
- *
- * @includeFunction ../../test/iterators/IteratorsTest.kt toStringJoinsNoMoreThanTheFirstTenElements
- */
-inline fun <T> java.util.Iterator<T>.toString(): String = join(separator = ", ", limit = 10)
diff --git a/libraries/stdlib/src/kotlin/JavaCollections.kt b/libraries/stdlib/src/kotlin/JavaCollections.kt
index bea1097e106..8f31dd5c165 100644
--- a/libraries/stdlib/src/kotlin/JavaCollections.kt
+++ b/libraries/stdlib/src/kotlin/JavaCollections.kt
@@ -2,6 +2,13 @@ package kotlin
 
 import java.util.*
 
+//
+// This file contains methods which are optimised for working on Collection / Array collections where the size
+// could be used to implement a more optimal solution
+//
+// See [[GenerateStandardLib.kt]] for more details
+//
+
 /**
  * Returns a new List containing the results of applying the given function to each element in this collection
  *
diff --git a/libraries/stdlib/src/kotlin/JavaIterablesLazy.kt b/libraries/stdlib/src/kotlin/JavaIterablesLazy.kt
index 6c467a09d79..a2019d2cd92 100644
--- a/libraries/stdlib/src/kotlin/JavaIterablesLazy.kt
+++ b/libraries/stdlib/src/kotlin/JavaIterablesLazy.kt
@@ -64,7 +64,7 @@ inline fun <T> java.lang.Iterable<T>.takeWhile(predicate: (T) -> Boolean): List<
  *
  * @includeFunction ../../test/CollectionTest.kt join
  */
-inline fun <T> java.lang.Iterable<T>.join(separator: String, prefix: String = "", postfix: String = "") : String {
+inline fun <T> java.lang.Iterable<T>.join(separator: String = ", ", prefix: String = "", postfix: String = "") : String {
     val buffer = StringBuilder(prefix)
     var first = true
     for (element in this) {
diff --git a/libraries/stdlib/test/iterators/IteratorsTest.kt b/libraries/stdlib/test/iterators/IteratorsTest.kt
index caf00e89626..810b96fdf4a 100644
--- a/libraries/stdlib/test/iterators/IteratorsTest.kt
+++ b/libraries/stdlib/test/iterators/IteratorsTest.kt
@@ -52,8 +52,8 @@ class IteratorsTest {
     }
 
     Test fun toStringJoinsNoMoreThanTheFirstTenElements() {
-        assertEquals("0, 1, 1, 2, 3, 5, 8, 13, 21, 34, ...", fibonacci().toString())
-        assertEquals("13, 21, 34, 55, 89, 144, 233, 377, 610, 987, ...", fibonacci().filter {  it > 10 }.toString())
-        assertEquals("144, 233, 377, 610, 987", fibonacci().filter { it > 100 }.takeWhile { it < 1000 }.toString())
+        assertEquals("0, 1, 1, 2, 3, 5, 8, 13, 21, 34, ...", fibonacci().join(limit = 10))
+        assertEquals("13, 21, 34, 55, 89, 144, 233, 377, 610, 987, ...", fibonacci().filter {  it > 10 }.join(limit = 10))
+        assertEquals("144, 233, 377, 610, 987", fibonacci().filter { it > 100 }.takeWhile { it < 1000 }.join())
     }
 }