Deprecate Clock.asTimeSource (#450)

Fixes #372

Author: dkhalanskyjb

core/common/src/Clock.kt

@@ -78,7 +78,11 @@ public fun Clock.todayIn(timeZone: TimeZone): LocalDate =
  * Please only use this conversion function on the [Clock] instances that are fully controlled programmatically.
  */
 @ExperimentalTime
+@Deprecated("This function is deprecated because Clock.System.asTimeSource " +
+        "can be confused with TimeSource.Monotonic, which are very different. " +
+        "See https://github.com/Kotlin/kotlinx-datetime/issues/372", level = DeprecationLevel.WARNING)
 public fun Clock.asTimeSource(): TimeSource.WithComparableMarks = object : TimeSource.WithComparableMarks {
+    @ExperimentalTime
     override fun markNow(): ComparableTimeMark = InstantTimeMark(now(), this@asTimeSource)
 }
 

core/common/test/ClockTimeSourceTest.kt

@@ -13,6 +13,7 @@ import kotlin.time.Duration.Companion.nanoseconds
 import kotlin.time.Duration.Companion.seconds
 
 @OptIn(ExperimentalTime::class)
+@Suppress("DEPRECATION")
 class ClockTimeSourceTest {
     @Test
     fun arithmetic() {