update: second text review

core/common/src/Clock.kt

@@ -21,8 +21,8 @@ public interface Clock {
     /**
      * Returns the [Instant] corresponding to the current time, according to this clock.
      *
-     * It is not guaranteed that calling [now] later will return a larger [Instant].
-     * In particular, for [Clock.System] it is completely expected that the opposite will happen,
+     * Calling [now] later is not guaranteed to return a larger [Instant].
+     * In particular, for [Clock.System], the opposite is completely expected,
      * and it must be taken into account.
      * See the [System] documentation for details.
      *

core/common/src/DateTimePeriod.kt

@@ -34,7 +34,7 @@ import kotlinx.serialization.Serializable
  * represented by a [DateTimeUnit] directly instead of a [DateTimePeriod]:
  * for example, instead of `DateTimePeriod(months = 6)`, one could use `DateTimeUnit.MONTH * 6`.
  * This provides a wider variety of operations: for example, finding how many such intervals fit between two instants
- * or dates or adding a multiple of such intervals at once.
+ * or dates or adding multiple intervals at once.
  *
  * ### Interaction with other entities
  *
@@ -527,7 +527,7 @@ internal fun buildDateTimePeriod(totalMonths: Int = 0, days: Int = 0, totalNanos
 /**
  * Constructs a new [DateTimePeriod]. If all the time components are zero, returns a [DatePeriod].
  *
- * It is recommended to always explicitly name the arguments when constructing this manually,
+ * It is always recommended to name the arguments explicitly when constructing this manually,
  * like `DateTimePeriod(years = 1, months = 12, days = 16)`.
  *
  * The passed numbers are not stored as is but are normalized instead for human readability, so, for example,

core/common/src/DateTimeUnit.kt

@@ -39,7 +39,7 @@ import kotlin.time.Duration.Companion.nanoseconds
  * "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 values with different
- * kinds of units, but in exchange, the duration of time between two [Instant] or [LocalDate] values can be
+ * kinds of units. However, 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
@@ -169,8 +169,8 @@ public sealed class DateTimeUnit {
      *
      * The reason lies in time zone transitions, because of which some days can be 23 or 25 hours.
      * For example, we say that exactly a whole day has passed between `2019-10-27T02:59` and `2019-10-28T02:59`
-     * in Berlin, despite the fact that the clocks were turned back one hour, so there are, in fact, 25 hours
-     * between the two date-times.
+     * in Berlin, even though the clocks were turned back one hour, so there are, in fact, 25 hours
+     * between the two date/times.
      *
      * @see DateTimeUnit for a description of date-time units in general.
      * @sample kotlinx.datetime.test.samples.DateTimeUnitSamples.dayBasedUnit

core/common/src/DayOfWeek.kt

@@ -31,7 +31,7 @@ public expect enum class DayOfWeek {
 public val DayOfWeek.isoDayNumber: Int get() = ordinal + 1
 
 /**
- * Returns the [DayOfWeek] instance for the given ISO 8601 week day number. Monday is 1, Sunday is 7.
+ * Returns the [DayOfWeek] instance for the given ISO 8601 weekday number. Monday is 1, and Sunday is 7.
  *
  * @throws IllegalArgumentException if the day number is not in the range 1..7
  * @sample kotlinx.datetime.test.samples.DayOfWeekSamples.constructorFunction

core/common/src/Instant.kt

@@ -15,7 +15,7 @@ import kotlin.time.*
 /**
  * A moment in time.
  *
- * A point in time must be uniquely identified so that it is independent of a time zone.
+ * A point in time must be uniquely identified to be independent of a time zone.
  * For example, `1970-01-01, 00:00:00` does not represent a moment in time since this would happen at different times
  * in different time zones: someone in Tokyo would think it is already `1970-01-01` several hours earlier than someone in
  * Berlin would. To represent such entities, use [LocalDateTime].
@@ -36,7 +36,7 @@ import kotlin.time.*
  * ```
  *
  * 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 it may be adjusted by the user or the system at any time,
+ * Note that this clock is not guaranteed to be monotonic, and the user or the system may adjust it at any time,
  * so it should not be used for measuring time intervals.
  * For that, consider using [TimeSource.Monotonic] and [TimeMark] instead of [Clock.System] and [Instant].
  *
@@ -121,7 +121,7 @@ import kotlin.time.*
  * // Two months, three days, four hours, and five minutes until the concert
  * ```
  *
- * or [Instant.until] method, as well as [Instant.daysUntil], [Instant.monthsUntil],
+ * Or the [Instant.until] method, as well as [Instant.daysUntil], [Instant.monthsUntil],
  * and [Instant.yearsUntil] extension functions:
  *
  * ```
@@ -223,7 +223,7 @@ public expect class Instant : Comparable<Instant> {
     /**
      * Returns the number of milliseconds from the epoch instant `1970-01-01T00:00:00Z`.
      *
-     * Any fractional part of millisecond is rounded toward zero to the whole number of milliseconds.
+     * Any fractional part of a millisecond is rounded toward zero to the whole number of milliseconds.
      *
      * If the result does not fit in [Long], returns [Long.MAX_VALUE] for a positive result or [Long.MIN_VALUE] for a negative result.
      *
@@ -362,13 +362,13 @@ public expect class Instant : Comparable<Instant> {
         /**
          * A shortcut for calling [DateTimeFormat.parse], followed by [DateTimeComponents.toInstantUsingOffset].
          *
-         * Parses a string that represents an instant including date and time components and a mandatory
+         * Parses a string that represents an instant, including date and time components and a mandatory
          * time zone offset and returns the parsed [Instant] value.
          *
          * The string is considered to represent time on the UTC-SLS time scale instead of UTC.
          * In practice, this means that, even if there is a leap second on the given day, it will not affect how the
          * time is parsed, even if it's in the last 1000 seconds of the day.
-         * Instead, even if there is a negative leap second on the given day, 23:59:59 is still considered valid time.
+         * Instead, even if there is a negative leap second on the given day, 23:59:59 is still considered a valid time.
          * 23:59:60 is invalid on UTC-SLS, so parsing it will fail.
          *
          * If the format is not specified, [DateTimeComponents.Formats.ISO_DATE_TIME_OFFSET] is used.

core/common/src/LocalDateTime.kt

@@ -21,7 +21,7 @@ import kotlinx.serialization.Serializable
  * 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.
+ * In all other cases, when a specific time zone is known, it is recommended to use [Instant] instead.
  *
  * ### Arithmetic operations
  *
@@ -206,7 +206,7 @@ public expect class LocalDateTime : Comparable<LocalDateTime> {
      * - [second] `0..59`
      * - [nanosecond] `0..999_999_999`
      *
-     * @throws IllegalArgumentException if any parameter is out of range,
+     * @throws IllegalArgumentException if any parameter is out of range
      * or if [dayOfMonth] is invalid for the given [monthNumber] and [year].
      *
      * @sample kotlinx.datetime.test.samples.LocalDateTimeSamples.constructorFunctionWithMonthNumber

core/common/src/LocalTime.kt

@@ -29,7 +29,7 @@ import kotlinx.serialization.Serializable
  *
  * ### Arithmetic operations
  *
- * Arithmetic operations on [LocalTime] are not provided, because they are not well-defined without a date and
+ * Arithmetic operations on [LocalTime] are not provided because they are not well-defined without a date and
  * a time zone.
  * See [LocalDateTime] for an explanation of why not accounting for time zone transitions may lead to incorrect results.
  * To perform arithmetic operations on time values, first, obtain an [Instant].
@@ -42,8 +42,8 @@ import kotlinx.serialization.Serializable
  * val timeThreeHoursLater = instantThreeHoursLater.toLocalDateTime(TimeZone.currentSystemDefault()).time
  * ```
  *
- * Because this pattern is extremely verbose and difficult to get right, it is recommended to work exclusively
- * with [Instant] and only obtain a [LocalTime] when it is necessary to display the time to the user.
+ * Since this pattern is extremely verbose and difficult to get right, it is recommended to work exclusively
+ * with [Instant] and only obtain a [LocalTime] when displaying the time to the user.
  *
  * ### Platform specifics
  *
@@ -53,10 +53,10 @@ import kotlinx.serialization.Serializable
  *
  * ### Construction, serialization, and deserialization
  *
- * [LocalTime] can be constructed directly from its components, using the constructor. See sample 1.
+ * [LocalTime] can be constructed directly from its components using the constructor. See sample 1.
  *
  * [fromSecondOfDay], [fromMillisecondOfDay], and [fromNanosecondOfDay] can be used to obtain a [LocalTime] from the
- * number of seconds, milliseconds, or nanoseconds since the start of the day, assuming there the offset from the UTC
+ * number of seconds, milliseconds, or nanoseconds since the start of the day, assuming that the offset from the UTC
  * does not change during the day.
  * [toSecondOfDay], [toMillisecondOfDay], and [toNanosecondOfDay] are the inverse operations.
  * See sample 2.
@@ -106,7 +106,7 @@ public expect class LocalTime : Comparable<LocalTime> {
          *
          * 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
+         * The reason is that, due to 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.
          *
@@ -127,7 +127,7 @@ public expect class LocalTime : Comparable<LocalTime> {
          *
          * 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
+         * The reason is that, due to 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.
          *
@@ -147,7 +147,7 @@ public expect class LocalTime : Comparable<LocalTime> {
          *
          * 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
+         * The reason is that, due to 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.
          *
@@ -262,7 +262,7 @@ public expect class LocalTime : Comparable<LocalTime> {
      * Returns the time as a second of a day, in `0 until 24 * 60 * 60`.
      *
      * Note that this is *not* the number of seconds since the start of the day!
-     * For example, `LocalTime(4, 0).toMillisecondOfDay()` will return `4 * 60 * 60`, the four hours'
+     * For example, `LocalTime(4, 0).toMillisecondOfDay()` will return `4 * 60 * 60`, the four hours
      * worth of seconds, but because of DST transitions, when clocks show 4:00, in fact, three, four, five, or
      * some other number of hours could have passed since the day started.
      * Use [Instant] to perform reliable time arithmetic.
@@ -359,7 +359,7 @@ public fun String.toLocalTime(): LocalTime = LocalTime.parse(this)
 /**
  * Combines this time's components with the specified date components into a [LocalDateTime] value.
  *
- * There is no check of whether the time is valid on the specified date, because that depends on a time zone, which
+ * There is no check of whether the time is valid on the specified date because that depends on the time zone, which
  * this method does not accept.
  *
  * @sample kotlinx.datetime.test.samples.LocalTimeSamples.atDateComponentWiseMonthNumber
@@ -370,7 +370,7 @@ public fun LocalTime.atDate(year: Int, monthNumber: Int, dayOfMonth: Int = 0): L
 /**
  * Combines this time's components with the specified date components into a [LocalDateTime] value.
  *
- * There is no check of whether the time is valid on the specified date, because that depends on a time zone, which
+ * There is no check of whether the time is valid on the specified date because that depends on the time zone, which
  * this method does not accept.
  *
  * @sample kotlinx.datetime.test.samples.LocalTimeSamples.atDateComponentWise
@@ -381,7 +381,7 @@ public fun LocalTime.atDate(year: Int, month: Month, dayOfMonth: Int = 0): Local
 /**
  * Combines this time's components with the specified [LocalDate] components into a [LocalDateTime] value.
  *
- * There is no check of whether the time is valid on the specified date, because that depends on a time zone, which
+ * There is no check of whether the time is valid on the specified date because that depends on the time zone, which
  * this method does not accept.
  *
  * @sample kotlinx.datetime.test.samples.LocalTimeSamples.atDate

core/common/src/TimeZone.kt

@@ -108,7 +108,7 @@ public expect open class TimeZone {
      * Return the civil date/time value that this instant has in the time zone provided as an implicit receiver.
      *
      * Note that while this conversion is unambiguous, the inverse ([LocalDateTime.toInstant])
-     * is not necessary so.
+     * is not necessarily so.
      *
      * @see LocalDateTime.toInstant
      * @see Instant.offsetIn
@@ -121,12 +121,12 @@ public expect open class TimeZone {
      * Returns an instant that corresponds to this civil date/time value in the time zone provided as an implicit receiver.
      *
      * Note that the conversion is not always well-defined. There can be the following possible situations:
-     * - There's only one instant that has this date/time value in the [timeZone].
+     * - Only one instant has this date/time value in the [timeZone].
      *   In this case, the conversion is unambiguous.
-     * - There's no instant that has this date/time value in the [timeZone].
+     * - No instant has this date/time value in the [timeZone].
      *   Such a situation appears when the time zone experiences a transition from a lesser to a greater offset.
      *   In this case, the conversion is performed with the lesser (earlier) offset, as if the time gap didn't occur yet.
-     * - There are two possible instants that can have this date/time components in the [timeZone].
+     * - Two possible instants can have these date/time components in the [timeZone].
      *   In this case, the earlier instant is returned.
      *
      * @see Instant.toLocalDateTime
@@ -176,7 +176,7 @@ public typealias ZoneOffset = FixedOffsetTimeZone
 /**
  * Finds the offset from UTC this time zone has at the specified [instant] of physical time.
  *
- * **Pitfall**: the offset returned from this function should typically not be used for datetime arithmetics,
+ * **Pitfall**: the offset returned from this function should typically not be used for date/time arithmetics
  * because the offset can change over time due to daylight-saving-time transitions and other reasons.
  * Use [TimeZone] directly with arithmetic operations instead.
  *
@@ -190,7 +190,7 @@ public expect fun TimeZone.offsetAt(instant: Instant): UtcOffset
  * Returns a civil date/time value that this instant has in the specified [timeZone].
  *
  * Note that while this conversion is unambiguous, the inverse ([LocalDateTime.toInstant])
- * is not necessary so.
+ * is not necessarily so.
  *
  * @see LocalDateTime.toInstant
  * @see Instant.offsetIn
@@ -202,7 +202,7 @@ public expect fun Instant.toLocalDateTime(timeZone: TimeZone): LocalDateTime
 /**
  * Returns a civil date/time value that this instant has in the specified [UTC offset][offset].
  *
- * **Pitfall**: it is typically more robust to use [TimeZone] directly, because the offset can change over time due to
+ * **Pitfall**: it is typically more robust to use [TimeZone] directly because the offset can change over time due to
  * daylight-saving-time transitions and other reasons, so [this] instant may actually correspond to a different offset
  * in the implied time zone.
  *
@@ -215,7 +215,7 @@ internal expect fun Instant.toLocalDateTime(offset: UtcOffset): LocalDateTime
 /**
  * Finds the offset from UTC the specified [timeZone] has at this instant of physical time.
  *
- * **Pitfall**: the offset returned from this function should typically not be used for datetime arithmetics,
+ * **Pitfall**: the offset returned from this function should typically not be used for date/time arithmetics
  * because the offset can change over time due to daylight-saving-time transitions and other reasons.
  * Use [TimeZone] directly with arithmetic operations instead.
  *
@@ -230,12 +230,12 @@ public fun Instant.offsetIn(timeZone: TimeZone): UtcOffset =
  * Returns an instant that corresponds to this civil date/time value in the specified [timeZone].
  *
  * Note that the conversion is not always well-defined. There can be the following possible situations:
- * - There's only one instant that has this date/time value in the [timeZone].
+ * - Only one instant has this date/time value in the [timeZone].
  *   In this case, the conversion is unambiguous.
- * - There's no instant that has this date/time value in the [timeZone].
+ * - No instant has this date/time value in the [timeZone].
  *   Such a situation appears when the time zone experiences a transition from a lesser to a greater offset.
  *   In this case, the conversion is performed with the lesser (earlier) offset, as if the time gap didn't occur yet.
- * - There are two possible instants that can have this date/time components in the [timeZone].
+ * - Two possible instants can have these date/time components in the [timeZone].
  *   In this case, the earlier instant is returned.
  *
  * @see Instant.toLocalDateTime
@@ -255,8 +255,8 @@ public expect fun LocalDateTime.toInstant(offset: UtcOffset): Instant
  * Returns an instant that corresponds to the start of this date in the specified [timeZone].
  *
  * Note that it's not equivalent to `atTime(0, 0).toInstant(timeZone)`
- * because a day does not always start at the fixed time 00:00:00.
- * For example, if due do daylight saving time, clocks were shifted from 23:30
+ * because a day does not always start at a fixed time 00:00:00.
+ * For example, if, due to daylight saving time, clocks were shifted from 23:30
  * of one day directly to 00:30 of the next day, skipping the midnight, then
  * `atStartOfDayIn` would return the `Instant` corresponding to 00:30, whereas
  * `atTime(0, 0).toInstant(timeZone)` would return the `Instant` corresponding