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