From 3f7a0d0845ec36586e38398b994a17d6ce961c6c Mon Sep 17 00:00:00 2001
From: Ilya Gorbunov <ilya.gorbunov@jetbrains.com>
Date: Sat, 25 May 2019 14:28:50 +0300
Subject: [PATCH] Rename DurationMeasured to TimedValue, withMeasureTime to
 measuredTimeValue

Add measureTime docs
---
 libraries/stdlib/src/kotlin/time/Clock.kt     |  2 +-
 .../stdlib/src/kotlin/time/measureTime.kt     | 57 ++++++++++++++-----
 libraries/stdlib/test/time/MeasureTimeTest.kt |  4 +-
 3 files changed, 45 insertions(+), 18 deletions(-)

diff --git a/libraries/stdlib/src/kotlin/time/Clock.kt b/libraries/stdlib/src/kotlin/time/Clock.kt
index dd250dbb337..328858b93cd 100644
--- a/libraries/stdlib/src/kotlin/time/Clock.kt
+++ b/libraries/stdlib/src/kotlin/time/Clock.kt
@@ -11,7 +11,7 @@ package kotlin.time
  * The only operation provided by the clock is [mark]. It returns a [ClockMark], which can be used to query the elapsed time later.
  *
  * @see [measureTime]
- * @see [withMeasureTime]
+ * @see [measureTimedValue]
  */
 public interface Clock {
     /**
diff --git a/libraries/stdlib/src/kotlin/time/measureTime.kt b/libraries/stdlib/src/kotlin/time/measureTime.kt
index e65c7847628..a21b1e1a5b0 100644
--- a/libraries/stdlib/src/kotlin/time/measureTime.kt
+++ b/libraries/stdlib/src/kotlin/time/measureTime.kt
@@ -7,42 +7,69 @@ package kotlin.time
 
 import kotlin.contracts.*
 
-public inline fun measureTime(action: () -> Unit): Duration {
+/**
+ * Executes the given function [block] and returns the duration of elapsed time interval.
+ *
+ * The elapsed time is measured with [MonoClock].
+ */
+public inline fun measureTime(block: () -> Unit): Duration {
     contract {
-        callsInPlace(action, InvocationKind.EXACTLY_ONCE)
+        callsInPlace(block, InvocationKind.EXACTLY_ONCE)
     }
-    return MonoClock.measureTime(action)
+    return MonoClock.measureTime(block)
 }
 
 
-public inline fun Clock.measureTime(action: () -> Unit): Duration {
+/**
+ * Executes the given function [block] and returns the duration of elapsed time interval.
+ *
+ * The elapsed time is measured with the specified `this` [Clock] instance.
+ */
+public inline fun Clock.measureTime(block: () -> Unit): Duration {
     contract {
-        callsInPlace(action, InvocationKind.EXACTLY_ONCE)
+        callsInPlace(block, InvocationKind.EXACTLY_ONCE)
     }
 
     val mark = mark()
-    action()
+    block()
     return mark.elapsed()
 }
 
 
+/**
+ * Data class representing a result of executing an action, along with the duration of elapsed time interval.
+ *
+ * @property value the result of the action.
+ * @property duration the time elapsed to execute the action.
+ */
+public data class TimedValue<T>(val value: T, val duration: Duration)
 
-public data class DurationMeasured<T>(val value: T, val duration: Duration)
-
-public inline fun <T> withMeasureTime(action: () -> T): DurationMeasured<T> {
+/**
+ * Executes the given function [block] and returns an instance of [TimedValue] class, containing both
+ * the result of the function execution and the duration of elapsed time interval.
+ *
+ * The elapsed time is measured with [MonoClock].
+ */
+public inline fun <T> measureTimedValue(block: () -> T): TimedValue<T> {
     contract {
-        callsInPlace(action, InvocationKind.EXACTLY_ONCE)
+        callsInPlace(block, InvocationKind.EXACTLY_ONCE)
     }
 
-    return MonoClock.withMeasureTime(action)
+    return MonoClock.measureTimedValue(block)
 }
 
-public inline fun <T> Clock.withMeasureTime(action: () -> T): DurationMeasured<T> {
+/**
+ * Executes the given [block] and returns an instance of [TimedValue] class, containing both
+ * the result of function execution and the duration of elapsed time interval.
+ *
+ * The elapsed time is measured with the specified `this` [Clock] instance.
+ */
+public inline fun <T> Clock.measureTimedValue(block: () -> T): TimedValue<T> {
     contract {
-        callsInPlace(action, InvocationKind.EXACTLY_ONCE)
+        callsInPlace(block, InvocationKind.EXACTLY_ONCE)
     }
 
     val mark = mark()
-    val result = action()
-    return DurationMeasured(result, mark.elapsed())
+    val result = block()
+    return TimedValue(result, mark.elapsed())
 }
diff --git a/libraries/stdlib/test/time/MeasureTimeTest.kt b/libraries/stdlib/test/time/MeasureTimeTest.kt
index 73fe8d58117..b3bfd4ba609 100644
--- a/libraries/stdlib/test/time/MeasureTimeTest.kt
+++ b/libraries/stdlib/test/time/MeasureTimeTest.kt
@@ -36,7 +36,7 @@ class MeasureTimeTest {
     fun measureTimeAndResult() {
         val someResult: String
 
-        val measured: DurationMeasured<String> = withMeasureTime { longRunningCalc().also { someResult = it } }
+        val measured: TimedValue<String> = measureTimedValue { longRunningCalc().also { someResult = it } }
         println("measured: $measured")
 
         val (result, elapsed) = measured
@@ -57,7 +57,7 @@ class MeasureTimeTest {
 
         val expectedResult: Long
 
-        val (result, elapsed2) = clock.withMeasureTime {
+        val (result, elapsed2) = clock.measureTimedValue {
             clock.reading += expectedNs
             expectedResult = expectedNs
             expectedNs