Address the review

core/common/src/DateTimePeriod.kt

@@ -422,7 +422,7 @@ public fun String.toDateTimePeriod(): DateTimePeriod = DateTimePeriod.parse(this
  * on [LocalDates][LocalDate], but they also can be passed anywhere a [DateTimePeriod] is expected.
  *
  * On the JVM, there are `DatePeriod.toJavaPeriod()` and `java.time.Period.toKotlinDatePeriod()`
- * extension functions.
+ * extension functions to convert between `kotlinx.datetime` and `java.time` objects used for the same purpose.
  *
  * @sample kotlinx.datetime.test.samples.DateTimePeriodSamples.DatePeriodSamples.simpleParsingAndFormatting
  */

core/common/src/Instant.kt

@@ -133,8 +133,10 @@ import kotlin.time.*
  *
  * ### Platform specifics
  *
- * On the JVM, there are `Instant.toJavaInstant()` and `java.time.Instant.toKotlinInstant()` extension functions.
- * On the Darwin platforms, there are `Instant.toNSDate()` and `NSDate.toKotlinInstant()` extension functions.
+ * On the JVM, there are `Instant.toJavaInstant()` and `java.time.Instant.toKotlinInstant()`
+ * extension functions to convert between `kotlinx.datetime` and `java.time` objects used for the same purpose.
+ * Similarly, on the Darwin platforms, there are `Instant.toNSDate()` and `NSDate.toKotlinInstant()`
+ * extension functions.
  *
  * ### Construction, serialization, and deserialization
  *

core/common/src/LocalDate.kt

@@ -35,8 +35,9 @@ import kotlinx.serialization.Serializable
  * [Instant.DISTANT_PAST] and [Instant.DISTANT_FUTURE].
  *
  * On the JVM,
- * there are `LocalDate.toJavaLocalDate()` and `java.time.LocalDate.toKotlinLocalDate()` extension functions.
- * On the Darwin platforms, there is a `LocalDate.toNSDateComponents()` extension function.
+ * there are `LocalDate.toJavaLocalDate()` and `java.time.LocalDate.toKotlinLocalDate()`
+ * extension functions to convert between `kotlinx.datetime` and `java.time` objects used for the same purpose.
+ * Similarly, on the Darwin platforms, there is a `LocalDate.toNSDateComponents()` extension function.
  *
  * ### Construction, serialization, and deserialization
  *

core/common/src/LocalDateTime.kt

@@ -66,8 +66,8 @@ import kotlinx.serialization.Serializable
  * [Instant.DISTANT_PAST] and [Instant.DISTANT_FUTURE].
  *
  * On the JVM, there are `LocalDateTime.toJavaLocalDateTime()` and `java.time.LocalDateTime.toKotlinLocalDateTime()`
- * extension functions.
- * On the Darwin platforms, there is a `LocalDateTime.toNSDateComponents()` extension function.
+ * extension functions to convert between `kotlinx.datetime` and `java.time` objects used for the same purpose.
+ * Similarly, on the Darwin platforms, there is a `LocalDateTime.toNSDateComponents()` extension function.
  *
  * ### Construction, serialization, and deserialization
  *

core/common/src/LocalTime.kt

@@ -48,7 +48,8 @@ import kotlinx.serialization.Serializable
  * ### Platform specifics
  *
  * On the JVM,
- * there are `LocalTime.toJavaLocalTime()` and `java.time.LocalTime.toKotlinLocalTime()` extension functions.
+ * there are `LocalTime.toJavaLocalTime()` and `java.time.LocalTime.toKotlinLocalTime()`
+ * extension functions to convert between `kotlinx.datetime` and `java.time` objects used for the same purpose.
  *
  * ### Construction, serialization, and deserialization
  *
@@ -103,7 +104,8 @@ public expect class LocalTime : Comparable<LocalTime> {
          * @throws IllegalArgumentException if [secondOfDay] is outside the `0 until 86400` range,
          * with 86400 being the number of seconds in a calendar day.
          *
-         * It is incorrect to pass the number of seconds since the start of the day to this function.
+         * It is incorrect to pass to this function
+         * the number of seconds that have physically elapsed since the start of the day.
          * The reason is that, due to the daylight-saving-time transitions, the number of seconds since the start
          * of the day is not a constant value: clocks could be shifted by an hour or more on some dates.
          * Use [Instant] to perform reliable time arithmetic.
@@ -123,7 +125,8 @@ public expect class LocalTime : Comparable<LocalTime> {
          * @throws IllegalArgumentException if [millisecondOfDay] is outside the `0 until 86400 * 1_000` range,
          * with 86400 being the number of seconds in a calendar day.
          *
-         * It is incorrect to pass the number of milliseconds since the start of the day to this function.
+         * It is incorrect to pass to this function
+         * the number of milliseconds that have physically elapsed since the start of the day.
          * The reason is that, due to the daylight-saving-time transitions, the number of milliseconds since the start
          * of the day is not a constant value: clocks could be shifted by an hour or more on some dates.
          * Use [Instant] to perform reliable time arithmetic.
@@ -142,7 +145,8 @@ public expect class LocalTime : Comparable<LocalTime> {
          * @throws IllegalArgumentException if [nanosecondOfDay] is outside the `0 until 86400 * 1_000_000_000` range,
          * with 86400 being the number of seconds in a calendar day.
          *
-         * It is incorrect to pass the number of nanoseconds since the start of the day to this function.
+         * It is incorrect to pass to this function
+         * the number of nanoseconds that have physically elapsed since the start of the day.
          * The reason is that, due to the daylight-saving-time transitions, the number of nanoseconds since the start
          * of the day is not a constant value: clocks could be shifted by an hour or more on some dates.
          * Use [Instant] to perform reliable time arithmetic.

core/common/src/TimeZone.kt

@@ -25,8 +25,10 @@ import kotlinx.serialization.Serializable
  * For interaction with `kotlinx-serialization`, [TimeZoneSerializer] is provided that serializes the time zone as its
  * identifier.
  *
- * On the JVM, there are `TimeZone.toJavaZoneId()` and `java.time.ZoneId.toKotlinTimeZone()` extension functions.
- * On the Darwin platforms, there are `TimeZone.toNSTimeZone()` and `NSTimeZone.toKotlinTimeZone()` extension functions.
+ * On the JVM, there are `TimeZone.toJavaZoneId()` and `java.time.ZoneId.toKotlinTimeZone()`
+ * extension functions to convert between `kotlinx.datetime` and `java.time` objects used for the same purpose.
+ * Similarly, on the Darwin platforms, there are `TimeZone.toNSTimeZone()` and `NSTimeZone.toKotlinTimeZone()` extension
+ * functions.
  *
  * @sample kotlinx.datetime.test.samples.TimeZoneSamples.usage
  */
@@ -142,7 +144,8 @@ public expect open class TimeZone {
  * changes in legislation or other reasons.
  *
  * On the JVM, there are `FixedOffsetTimeZone.toJavaZoneOffset()` and
- * `java.time.ZoneOffset.toKotlinFixedOffsetTimeZone()` extension functions.
+ * `java.time.ZoneOffset.toKotlinFixedOffsetTimeZone()`
+ * extension functions to convert between `kotlinx.datetime` and `java.time` objects used for the same purpose.
  * Note also the functions available for [TimeZone] in general.
  *
  * @sample kotlinx.datetime.test.samples.TimeZoneSamples.FixedOffsetTimeZoneSamples.casting

core/common/src/UtcOffset.kt

@@ -30,7 +30,7 @@ import kotlinx.serialization.Serializable
  * ### Platform specifics
  *
  * On the JVM, there are `UtcOffset.toJavaZoneOffset()` and `java.time.ZoneOffset.toKotlinUtcOffset()`
- * extension functions.
+ * extension functions to convert between `kotlinx.datetime` and `java.time` objects used for the same purpose.
  *
  * ### Construction, serialization, and deserialization
  *
@@ -218,8 +218,10 @@ public fun UtcOffset(): UtcOffset = UtcOffset.ZERO
 /**
  * Returns the fixed-offset time zone with the given UTC offset.
  *
- * **Pitfall**: if the offset is not fixed, the returned time zone will not reflect the changes in the offset.
- * Use [TimeZone.of] with a IANA timezone name to obtain a time zone that can handle changes in the offset.
+ * **Pitfall**: UTC offsets are static values and do not change with time.
+ * If the logic requires that the offset changes with time, for example, to account for daylight-saving-time
+ * transitions, use [TimeZone.of] with a IANA time zone name to obtain a time zone that can handle
+ * changes in the offset.
  *
  * @sample kotlinx.datetime.test.samples.UtcOffsetSamples.asFixedOffsetTimeZone
  */

core/common/src/format/LocalDateFormat.kt

@@ -111,7 +111,6 @@ private fun MonthNames.toKotlinCode(): String = when (this.names) {
  *
  * @sample kotlinx.datetime.test.samples.format.LocalDateFormatSamples.DayOfWeekNamesSamples.usage
  * @sample kotlinx.datetime.test.samples.format.LocalDateFormatSamples.DayOfWeekNamesSamples.constructionFromList
->>>>>>> 585441e (WIP: add samples for some formatting APIs)
  */
 public class DayOfWeekNames(
     /**