Address the review

proposals/stdlib/instant.md

@@ -45,7 +45,7 @@ Non-examples:
 ### `Clock`
 
 A `Clock` implementation is a way to obtain the current `Instant`.
-The `Clock.SYSTEM` default implementation, available on all platforms, queries
+The `Clock.System` default implementation, available on all platforms, queries
 the system clock (the one also used to display the current date and time in the
 corner of your screen).
 `Clock` does not provide the current time zone, and so it is not enough on its
@@ -101,7 +101,7 @@ This information is stored as `Instant` values.
 **Example**: listing all files that were modified in the last 24 hours.
 
 These calculations require knowing the current moment in time (accessed via
-`Clock.SYSTEM`) and the moment in time when some event happened.
+`Clock.System`) and the moment in time when some event happened.
 They do not require knowing the current system time zone: how long ago something
 happened does not depend on what exactly clocks said, it only depends on the
 actual passage of time. In fact, it's _incorrect_ to take the current time zone
@@ -217,10 +217,8 @@ The specifics of what gets added is given below.
  *
  * The [Clock] interface is the primary way to obtain the current moment:
  *
- * ```
- * val clock: Clock = Clock.System
- * val instant = clock.now()
- * ```
+ * - `val clock: Clock = Clock.System`
+ * - `val instant = clock.now()`
  *
  * The [Clock.System] implementation uses the platform-specific system clock to obtain the current moment.
  * Note that this clock is not guaranteed to be monotonic, and the user or the system may adjust it at any time,
@@ -231,16 +229,12 @@ The specifics of what gets added is given below.
  *
  * The [plus] and [minus] operators can be used to add [Duration]s to and subtract them from an [Instant]:
  *
- * ```
- * Clock.System.now() + 5.seconds // 5 seconds from now
- * ```
+ * - `Clock.System.now() + 5.seconds // 5 seconds from now`
  *
  * Also, there is a [minus] operator that returns the [Duration] representing the difference between two instants:
  *
- * ```
- * val kotlinRelease = Instant.parse("2016-02-15T02:00T12:00+03:00")
- * val kotlinStableDuration = Clock.System.now() - kotlinRelease
- * ```
+ * - `val kotlinRelease = Instant.parse("2016-02-15T02:00T12:00+03:00")`
+ * - `val kotlinStableDuration = Clock.System.now() - kotlinRelease`
  *
  * ### Platform specifics
  *
@@ -255,31 +249,25 @@ The specifics of what gets added is given below.
  * `1970-01-01T00:00:00Z` (the Unix epoch).
  * [epochSeconds] and [nanosecondsOfSecond] can be used to obtain the number of seconds and nanoseconds since the epoch.
  *
- * ```
- * val instant = Instant.fromEpochSeconds(1709898983, 123456789)
- * instant.epochSeconds // 1709898983
- * instant.nanosecondsOfSecond // 123456789
- * ```
+ * - `val instant = Instant.fromEpochSeconds(1709898983, 123456789)`
+ * - `instant.epochSeconds // 1709898983`
+ * - `instant.nanosecondsOfSecond // 123456789`
  *
  * [fromEpochMilliseconds] allows constructing an instant from the number of milliseconds since the epoch.
  * [toEpochMilliseconds] can be used to obtain the number of milliseconds since the epoch.
  * Note that [Instant] supports nanosecond precision, so converting to milliseconds is a lossy operation.
  *
- * ```
- * val instant1 = Instant.fromEpochSeconds(1709898983, 123456789)
- * instant1.nanosecondsOfSecond // 123456789
- * val milliseconds = instant1.toEpochMilliseconds() // 1709898983123
- * val instant2 = Instant.fromEpochMilliseconds(milliseconds)
- * instant2.nanosecondsOfSecond // 123000000
- * ```
+ * - `val instant1 = Instant.fromEpochSeconds(1709898983, 123456789)`
+ * - `instant1.nanosecondsOfSecond // 123456789`
+ * - `val milliseconds = instant1.toEpochMilliseconds() // 1709898983123`
+ * - `val instant2 = Instant.fromEpochMilliseconds(milliseconds)`
+ * - `instant2.nanosecondsOfSecond // 123000000`
  *
  * [parse] and [toString] methods can be used to obtain an [Instant] from and convert it to a string in the
  * ISO 8601 extended format.
  *
- * ```
- * val instant = Instant.parse("2023-01-02T22:35:01+01:00")
- * instant.toString() // 2023-01-02T21:35:01Z
- * ```
+ * - `val instant = Instant.parse("2023-01-02T22:35:01+01:00")`
+ * - `instant.toString() // 2023-01-02T21:35:01Z`
  */
 public expect class Instant : Comparable<Instant> {
 
@@ -815,7 +803,7 @@ val nextEvent =
         filter { it > currentTime }.minOrNull() ?: maxTimestamp
 
 if (nextEvent != maxTimestamp) {
-    println("The next event is $earliestEvent")
+    println("The next event is $nextEvent")
 } else {
     println("No events to execute")
 }
@@ -941,8 +929,9 @@ A common way to obtain the current `Instant` on the JVM is to call
 `Instant.now()`:
 
 * <https://grep.app/search?q=Instant.now%28%29> is 13000 hits as of writing.
-* <https://grep.app/search?q=Clock.systemUTC%28%29.instant%28%29> is less than
-  100 hits.
+* <https://grep.app/search?q=clock.instant%28%29> is about 1200 hits.
+  This isn't exhaustive, but gives an estimate of how often people use
+  dependency injection of clocks.
 
 It is not obvious to people who want to obtain the current `Instant` that a
 class like `Clock` even exists, so we direct them to it using a deprecation with
@@ -951,7 +940,7 @@ a proposed replacement.
 #### `DISTANT_PAST` + `DISTANT_FUTURE` + `isDistantPast` + `isDistantFuture`
 
 On the JVM, `Instant.MAX` and `Instant.MIN` are occasionally used as default
-values, mostly for the purposes of finding the earlies or the latest instant:
+values, mostly for the purposes of finding the earliest or the latest instant:
 
 ```kotlin
 var earliestEvent = java.time.Instant.MAX
@@ -1232,7 +1221,7 @@ fun epochSecondsLaterThanMaxInstant(epochSeconds: Long): Boolean =
     Exception: `Clock.asTimeSource` does not get the new overload.
   - For every function that returns but doesn't accept an `Instant`,
     hides it and adds a new function, one that returns `kotlin.time.Instant`,
-    but with a different `JvmName`.
+    but with different platform names.
   - Deprecates the `Instant` serializers with a warning.
   - A new version of `kotlinx-datetime` is published with this.
 * One major version of `kotlinx-datetime` later:
@@ -1269,7 +1258,7 @@ fun LocalDateTime.toInstant(): kotlinx.datetime.Instant
 
 fun kotlin.time.Instant.toLocalDateTime(): LocalDateTime
 
-@JvmName("temporary_toInstant")
+@JsName("temporary_toInstant") // and other PlatformName annotations
 fun LocalDateTime.toInstant(): kotlin.time.Instant
 
 // 0.X+2.0