From 75ae42121b4a53e8645a25bd570dc6cff5043b5a Mon Sep 17 00:00:00 2001
From: Ilya Gorbunov <ilya.gorbunov@jetbrains.com>
Date: Tue, 28 Feb 2017 22:15:41 +0300
Subject: [PATCH] Improve sample comments. Improve sample for lastIndex
 property.

---
 .../samples/test/samples/collections/collections.kt   |  4 +++-
 .../stdlib/samples/test/samples/collections/maps.kt   | 11 ++++++++---
 libraries/stdlib/samples/test/samples/text/regex.kt   |  6 ++++--
 3 files changed, 15 insertions(+), 6 deletions(-)

diff --git a/libraries/stdlib/samples/test/samples/collections/collections.kt b/libraries/stdlib/samples/test/samples/collections/collections.kt
index 5ae32fe755a..5da4791d185 100644
--- a/libraries/stdlib/samples/test/samples/collections/collections.kt
+++ b/libraries/stdlib/samples/test/samples/collections/collections.kt
@@ -28,7 +28,9 @@ class Collections {
         @Sample
         fun lastIndexOfList() {
             assertPrints(emptyList<Any>().lastIndex, "-1")
-            assertPrints(listOf("a", "x", "y").lastIndex, "2")
+            val list = listOf("a", "x", "y")
+            assertPrints(list.lastIndex, "2")
+            assertPrints(list[list.lastIndex], "y")
         }
     }
 
diff --git a/libraries/stdlib/samples/test/samples/collections/maps.kt b/libraries/stdlib/samples/test/samples/collections/maps.kt
index c2317a37a80..580526e102b 100644
--- a/libraries/stdlib/samples/test/samples/collections/maps.kt
+++ b/libraries/stdlib/samples/test/samples/collections/maps.kt
@@ -84,11 +84,16 @@ class Maps {
         @Sample
         fun getOrPut() {
             val map = mutableMapOf<String, Int?>()
-            assertPrints(map.getOrPut("x") { 2 }, "2")
-            assertPrints(map.getOrPut("x") { 3 }, "2") // still
 
+            assertPrints(map.getOrPut("x") { 2 }, "2")
+            // subsequent calls to getOrPut do not evaluate the default value
+            // since the first getOrPut has already stored value 2 in the map
+            assertPrints(map.getOrPut("x") { 3 }, "2")
+
+            // however null value mapped to a key is treated the same as the missing value
             assertPrints(map.getOrPut("y") { null }, "null")
-            assertPrints(map.getOrPut("y") { 42 }, "42") // but!
+            // so in that case the default value is evaluated
+            assertPrints(map.getOrPut("y") { 42 }, "42")
         }
 
         @Sample
diff --git a/libraries/stdlib/samples/test/samples/text/regex.kt b/libraries/stdlib/samples/test/samples/text/regex.kt
index 6dca16b17d8..f3f92c1e4e5 100644
--- a/libraries/stdlib/samples/test/samples/text/regex.kt
+++ b/libraries/stdlib/samples/test/samples/text/regex.kt
@@ -12,12 +12,14 @@ class Regexps {
         val match = Regex("(\\w+) (\\d+)").find(inputString)!!
         val (name, phone) = match.destructured
 
-        assertPrints(name, "John")
-        assertPrints(phone, "9731879")
+        assertPrints(name, "John")     // value of the first group matched by \w+
+        assertPrints(phone, "9731879") // value of the second group matched by \d+
 
+        // group with the zero index is the whole substring matched by the regular expression
         assertPrints(match.groupValues, "[John 9731879, John, 9731879]")
 
         val numberedGroupValues = match.destructured.toList()
+        // destructured group values only contain values of the groups, excluding the zeroth group.
         assertPrints(numberedGroupValues, "[John, 9731879]")
     }
 }
\ No newline at end of file