Add sample for setOf method

Ilya Gorbunov: Improve sample to illustrate stable iteration order and set equality.

libraries/stdlib/samples/test/samples/collections/collections.kt

@@ -271,6 +271,19 @@ class Collections {
             assertTrue(set == other, "Empty sets are equal")
             assertPrints(set, "[]")
         }
+
+        @Sample
+        fun readOnlySet() {
+            val set1 = setOf(1, 2, 3)
+            val set2 = setOf(3, 2, 1)
+
+            // setOf preserves the iteration order of elements
+            assertPrints(set1, "[1, 2, 3]")
+            assertPrints(set2, "[3, 2, 1]")
+
+            // but the sets with the same elements are equal no matter of order
+            assertTrue(set1 == set2)
+        }
     }
 
     class Transformations {

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

@@ -31,6 +31,7 @@ public fun <T> emptySet(): Set<T> = EmptySet
  * Returns a new read-only set with the given elements.
  * Elements of the set are iterated in the order they were specified.
  * The returned set is serializable (JVM).
+ * @sample samples.collections.Collections.Sets.readOnlySet
  */
 public fun <T> setOf(vararg elements: T): Set<T> = if (elements.size > 0) elements.toSet() else emptySet()