Rename DurationMeasured to TimedValue, withMeasureTime to measuredTimeValue

Add measureTime docs

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 {
     /**

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())
 }

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