update: second text review (#400)

Author: danil-pavlov

README.md

@@ -47,7 +47,7 @@ The library provides a basic set of types for working with date and time:
 - `DatePeriod` is a subclass of `DateTimePeriod` with zero time components,
 it represents a difference between two LocalDate values decomposed into date units.
 - `DateTimeUnit` provides a set of predefined date and time units to use in arithmetic operations on `Instant` and `LocalDate`. 
-- `UtcOffset` represents the amount of time the local date/time at a particular time zone differs from the date/time at UTC.
+- `UtcOffset` represents the amount of time the local datetime at a particular time zone differs from the datetime at UTC.
 
 ### Type use-cases
 
@@ -63,7 +63,7 @@ Here is some basic advice on how to choose which of the date-carrying types to u
   rules might change unexpectedly in the future. In this [blog post](https://codeblog.jonskeet.uk/2019/03/27/storing-utc-is-not-a-silver-bullet/), you can read more about why it's not always 
   a good idea to use `Instant` everywhere.
 
-  Also, use `LocalDateTime` to decode an `Instant` to its local date-time components for display and UIs.
+  Also, use `LocalDateTime` to decode an `Instant` to its local datetime components for display and UIs.
 
 - Use `LocalDate` to represent the date of an event that does not have a specific time associated with it (like a birth date).
 
@@ -99,7 +99,7 @@ An `Instant` is just a counter of high resolution time intervals since the begin
 To get human readable components from an `Instant` value, you need to convert it to the `LocalDateTime`
 type that represents date and time components without a reference to the particular time zone.
 
-The `TimeZone` type provides the rules to convert instants from and to date/time components.
+The `TimeZone` type provides the rules to convert instants from and to datetime components.
 
 ```kotlin
 val currentMoment: Instant = Clock.System.now()
@@ -172,7 +172,7 @@ val hourMinute = LocalTime(hour = 12, minute = 13)
 An `Instant` can be converted to a number of milliseconds since the Unix/POSIX epoch with the `toEpochMilliseconds()` function.
 To convert back, use the companion object function `Instant.fromEpochMilliseconds(Long)`.
 
-### Converting instant and local date/time to and from the ISO 8601 string
+### Converting instant and local datetime to and from the ISO 8601 string
 
 `Instant`, `LocalDateTime`, `LocalDate` and `LocalTime` provide shortcuts for
 parsing and formatting them using the extended ISO 8601 format.
@@ -268,7 +268,7 @@ dateTimeFormat.parse("2023-12-24T23:59:59")
 
 Sometimes, the required string format doesn't fully correspond to any of the
 classes `kotlinx-datetime` provides. In these cases, `DateTimeComponents`, a
-collection of all date-time fields, can be used instead.
+collection of all datetime fields, can be used instead.
 
 ```kotlin
 // import kotlinx.datetime.format.*
@@ -341,7 +341,7 @@ val diffInMonths = instantInThePast.until(Clock.System.now(), DateTimeUnit.MONTH
 ```
 There are also shortcuts `yearsUntil(...)`, `monthsUntil(...)`, and `daysUntil(...)`.
 
-A particular amount of date/time units or a date/time period can be added to an `Instant` with the `plus` function:
+A particular amount of datetime units or a datetime period can be added to an `Instant` with the `plus` function:
 
 ```kotlin
 val now = Clock.System.now()
@@ -395,7 +395,7 @@ val localDateTimeTwoDaysLater = instantTwoDaysLater.toLocalDateTime(timeZone)
 
 ## Implementation
 
-The implementation of date/time types, such as `Instant`, `LocalDateTime`, `TimeZone` and so on, relies on:
+The implementation of datetime types, such as `Instant`, `LocalDateTime`, `TimeZone` and so on, relies on:
 
 - in JVM: [`java.time`](https://docs.oracle.com/javase/8/docs/api/java/time/package-summary.html) API;
 - in Js and Wasm-Js: [`js-joda`](https://js-joda.github.io/js-joda/) library;
@@ -405,7 +405,7 @@ The implementation of date/time types, such as `Instant`, `LocalDateTime`, `Time
 ## Known/open issues, work TBD
 
 - [x] Some kind of `Clock` interface is needed as a pluggable replacement for `Instant.now()`.
-- [ ] Flexible locale-neutral parsing and formatting facilities are needed to support various date/time interchange
+- [ ] Flexible locale-neutral parsing and formatting facilities are needed to support various datetime interchange
   formats that are used in practice (in particular, various RFCs).
 
 ## Using in your projects

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

@@ -434,7 +434,7 @@ public class DatePeriod internal constructor(
     /**
      * Constructs a new [DatePeriod].
      *
-     * It is always recommended to name the arguments explicitly when constructing this manually,
+     * It is recommended to always name the arguments explicitly when constructing this manually,
      * like `DatePeriod(years = 1, months = 12, days = 16)`.
      *
      * The passed numbers are not stored as is but are normalized instead for human readability, so, for example,
@@ -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 recommended to always 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

@@ -14,9 +14,9 @@ import kotlin.time.Duration.Companion.nanoseconds
 /**
  * A unit for measuring time; for example, a second, 20 seconds, a day, a month, or a quarter.
  *
- * This class is used to express arithmetic operations like addition and subtraction on date-time values:
- * for example, adding 10 days to a date-time value, subtracting 5 hours from a date-time value, or finding the
- * number of 30-second intervals between two date-time values.
+ * This class is used to express arithmetic operations like addition and subtraction on datetime values:
+ * for example, adding 10 days to a datetime value, subtracting 5 hours from a datetime value, or finding the
+ * number of 30-second intervals between two datetime values.
  *
  * ### Interaction with other entities
  *
@@ -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
@@ -63,20 +63,20 @@ import kotlin.time.Duration.Companion.nanoseconds
 public sealed class DateTimeUnit {
 
     /**
-     * Produces a date-time unit that is a multiple of this unit times the specified integer [scalar] value.
+     * Produces a datetime unit that is a multiple of this unit times the specified integer [scalar] value.
      *
      * @throws ArithmeticException if the result overflows.
      * @sample kotlinx.datetime.test.samples.DateTimeUnitSamples.multiplication
      */
     public abstract operator fun times(scalar: Int): DateTimeUnit
 
     /**
-     * A [date-time unit][DateTimeUnit] that has the precise time duration.
+     * A [datetime unit][DateTimeUnit] that has the precise time duration.
      *
      * Such units are independent of the time zone.
      * Any such unit can be represented as some fixed number of nanoseconds.
      *
-     * @see DateTimeUnit for a description of date-time units in general.
+     * @see DateTimeUnit for a description of datetime units in general.
      * @sample kotlinx.datetime.test.samples.DateTimeUnitSamples.timeBasedUnit
      */
     @Serializable(with = TimeBasedDateTimeUnitSerializer::class)
@@ -141,13 +141,13 @@ public sealed class DateTimeUnit {
     }
 
     /**
-     * A [date-time unit][DateTimeUnit] equal to some number of days or months.
+     * A [datetime unit][DateTimeUnit] equal to some number of days or months.
      *
      * Operations involving `DateBased` units are performed on dates. The same operations on [Instants][Instant]
      * require a [TimeZone] to find the corresponding [LocalDateTimes][LocalDateTime] first to perform
      * the operation with the date component of these `LocalDateTime` values.
      *
-     * @see DateTimeUnit for a description of date-time units in general.
+     * @see DateTimeUnit for a description of datetime units in general.
      * @see DateTimeUnit.DayBased for specifically day-based units.
      * @see DateTimeUnit.MonthBased for specifically month-based units.
      */
@@ -162,17 +162,17 @@ public sealed class DateTimeUnit {
     }
 
     /**
-     * A [date-time unit][DateTimeUnit] equal to some number of calendar days.
+     * A [datetime unit][DateTimeUnit] equal to some number of calendar days.
      *
      * A calendar day is not considered identical to 24 hours.
      * Thus, a `DayBased` unit cannot be expressed as a multiple of some [TimeBased] unit.
      *
      * 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 datetimes.
      *
-     * @see DateTimeUnit for a description of date-time units in general.
+     * @see DateTimeUnit for a description of datetime units in general.
      * @sample kotlinx.datetime.test.samples.DateTimeUnitSamples.dayBasedUnit
      */
     @Serializable(with = DayBasedDateTimeUnitSerializer::class)
@@ -202,12 +202,12 @@ public sealed class DateTimeUnit {
     }
 
     /**
-     * A [date-time unit][DateTimeUnit] equal to some number of months.
+     * A [datetime unit][DateTimeUnit] equal to some number of months.
      *
      * Since different months have a different number of days, a `MonthBased` unit cannot be expressed
      * as a multiple of some [DayBased]-unit.
      *
-     * @see DateTimeUnit for a description of date-time units in general.
+     * @see DateTimeUnit for a description of datetime units in general.
      * @sample kotlinx.datetime.test.samples.DateTimeUnitSamples.monthBasedUnit
      */
     @Serializable(with = MonthBasedDateTimeUnitSerializer::class)

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/Exceptions.kt

@@ -6,7 +6,7 @@
 package kotlinx.datetime
 
 /**
- * Thrown by date-time arithmetic operations if the result cannot be computed or represented.
+ * Thrown by datetime arithmetic operations if the result cannot be computed or represented.
  */
 public class DateTimeArithmeticException: RuntimeException {
     public constructor(): super()

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 in a way that is 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].
  *
@@ -79,7 +79,7 @@ import kotlin.time.*
  * 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]:
+ * Durations can also be represented as multiples of some [time-based datetime unit][DateTimeUnit.TimeBased]:
  *
  * ```
  * Clock.System.now().plus(4, DateTimeUnit.HOUR) // 4 hours from now
@@ -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.