Address the comments

Author: dkhalanskyjb

core/common/src/DateTimeUnit.kt

@@ -35,11 +35,11 @@ import kotlin.time.Duration.Companion.nanoseconds
  * Arithmetic operations on [LocalDateTime] are not provided.
  * Please see the [LocalDateTime] documentation for a discussion.
  *
- * [DateTimePeriod] is a combination of all [DateTimeUnit] values, used to express things like
+ * [DateTimePeriod] is a combination of [DateTimeUnit] values of every kind, used to express things like
  * "two days and three hours."
  * [DatePeriod] is specifically a combination of [DateTimeUnit.DateBased] values.
- * [DateTimePeriod] is more flexible than [DateTimeUnit] because it can express a combination of different units or
- * have the length of zero, but in exchange, the duration of time between two [Instant] or [LocalDate] values can be
+ * [DateTimePeriod] is more flexible than [DateTimeUnit] because it can express a combination of values with different
+ * kinds of units, but in exchange, the duration of time between two [Instant] or [LocalDate] values can be
  * measured in terms of some [DateTimeUnit], but not [DateTimePeriod] or [DatePeriod].
  *
  * ### Construction, serialization, and deserialization
@@ -48,9 +48,9 @@ import kotlin.time.Duration.Companion.nanoseconds
  * [DateTimeUnit.MONTH], and others.
  *
  * Two ways are provided to create custom [DateTimeUnit] instances:
- * - By multiplying an existing unit on the right by an integer scalar: for example, `DateTimeUnit.NANOSECOND * 10`.
+ * - By multiplying an existing unit on the right by an integer scalar: for example, `DateTimeUnit.MICROSECOND * 10`.
  * - By constructing an instance manually with [TimeBased], [DayBased], or [MonthBased]: for example,
- *   `DateTimeUnit.TimeBased(nanoseconds = 10)`.
+ *   `DateTimeUnit.TimeBased(nanoseconds = 10_000)`.
  *
  * Also, [DateTimeUnit] can be serialized and deserialized using `kotlinx.serialization`:
  * [DateTimeUnitSerializer], [DateBasedDateTimeUnitSerializer], [DayBasedDateTimeUnitSerializer],

core/common/src/Instant.kt

@@ -76,7 +76,7 @@ import kotlin.time.*
  * The [plus] and [minus] operators can be used to add [Duration]s to and subtract them from an [Instant]:
  *
  * ```
- * Clock.System.now() + Duration.seconds(5) // 5 seconds from now
+ * Clock.System.now() + 5.seconds // 5 seconds from now
  * ```
  *
  * Durations can also be represented as multiples of some [time-based date-time unit][DateTimeUnit.TimeBased]:
@@ -631,7 +631,7 @@ public fun Instant.minus(unit: DateTimeUnit.TimeBased): Instant =
  * If the [value] is negative, the returned instant is earlier than this instant.
  *
  * Note that the time zone does not need to be passed when the [unit] is a time-based unit.
- * It is also not needed when adding date-based units to a [LocalDate].
+ * It is also not needed when adding date-based units to a [LocalDate][LocalDate.plus].
  *
  * @throws DateTimeArithmeticException if this value or the result is too large to fit in [LocalDateTime].
  * @sample kotlinx.datetime.test.samples.InstantSamples.plusDateTimeUnit

core/common/src/LocalDate.kt

@@ -263,6 +263,11 @@ public fun String.toLocalDate(): LocalDate = LocalDate.parse(this)
  * For finding an instant that corresponds to the start of a date in a particular time zone consider using
  * [LocalDate.atStartOfDayIn] function because a day does not always start at the fixed time 0:00:00.
  *
+ * **Pitfall**: since [LocalDateTime] is not tied to a particular time zone, the resulting [LocalDateTime] may not
+ * exist in the implicit time zone.
+ * For example, `LocalDate(2021, 3, 28).atTime(2, 16, 20)` will successfully create a [LocalDateTime],
+ * even though in Berlin, times between 2:00 and 3:00 do not exist on March 28, 2021 due to the transition to DST.
+ *
  * @sample kotlinx.datetime.test.samples.LocalDateSamples.atTimeInline
  */
 public fun LocalDate.atTime(hour: Int, minute: Int, second: Int = 0, nanosecond: Int = 0): LocalDateTime =
@@ -356,7 +361,7 @@ public operator fun LocalDate.minus(other: LocalDate): DatePeriod = other.period
  * - zero if this date is equal to the other.
  *
  * The value is rounded toward zero.
-
+ *
  * If the result does not fit in [Int], returns [Int.MAX_VALUE] for a positive result or [Int.MIN_VALUE] for a negative result.
  *
  * @see LocalDate.daysUntil
@@ -393,6 +398,8 @@ public expect fun LocalDate.monthsUntil(other: LocalDate): Int
 /**
  * Returns the number of whole years between two dates.
  *
+ * The value is rounded toward zero.
+ *
  * If the result does not fit in [Int], returns [Int.MAX_VALUE] for a positive result or [Int.MIN_VALUE] for a negative result.
  *
  * @see LocalDate.until

core/common/src/LocalDateTime.kt

@@ -18,10 +18,10 @@ import kotlinx.serialization.Serializable
  * For example, `2020-08-30T18:43` is not a *moment in time*, since someone in Berlin and someone in Tokyo would witness
  * this on their clocks at different times, but it is a [LocalDateTime].
  *
- * The main purpose of this class is to provide human-readable representations of [Instant] values, or to transfer them
- * as data.
- * Instances of [LocalDateTime] should not be stored when a specific time zone is known: in this case, it is recommended
- * to use [Instant] instead.
+ * The main purpose of this class is to provide human-readable representations of [Instant] values, to transfer them
+ * as data, or to define future planned events that will have the same local date-time even if the time zone rules
+ * change.
+ * In all other cases when a specific time zone is known, it is recommended to use [Instant] instead.
  *
  * ### Arithmetic operations
  *
@@ -30,7 +30,8 @@ import kotlinx.serialization.Serializable
  *
  * For example, in Berlin, naively adding one day to `2021-03-27T02:16:20` without accounting for the time zone would
  * result in `2021-03-28T02:16:20`.
- * However, this local date-time is invalid, because the clocks moved forward from `02:00` to `03:00` on that day.
+ * However, the resulting local date-time cannot be observed in that time zone,
+ * because the clocks moved forward from `02:00` to `03:00` on that day.
  * This is known as a "time gap", or a "spring forward" transition.
  *
  * Similarly, the local date-time `2021-10-31T02:16:20` is ambiguous,
@@ -39,8 +40,8 @@ import kotlinx.serialization.Serializable
  *
  * For these reasons, using [LocalDateTime] as an input to arithmetic operations is discouraged.
  *
- * When only arithmetic on the date component is needed, without touching the time, use [LocalDate] instead,
- * as it provides well-defined date arithmetic.
+ * When only the date component is needed, without the time, use [LocalDate] instead.
+ * It provides well-defined date arithmetic.
  *
  * If the time component must be taken into account, [LocalDateTime]
  * should be converted to [Instant] using a specific time zone, and the arithmetic on [Instant] should be used.
@@ -65,7 +66,8 @@ import kotlinx.serialization.Serializable
  * whether the given date and time components are valid in the implied time zone.
  * For example, `2021-03-28T02:16:20` is invalid in Berlin, as it falls into a time gap, but nothing prevents one
  * from constructing such a [LocalDateTime].
- * Before constructing a [LocalDateTime] using any API, please ensure that the result is valid in the implied time zone.
+ * Before using a [LocalDateTime] constructed using any API,
+ * please ensure that the result is valid in the implied time zone.
  * The recommended pattern is to convert a [LocalDateTime] to [Instant] as soon as possible (see
  * [LocalDateTime.toInstant]) and work with [Instant] values instead.
  *