feat: new docs review

Author: danil-pavlov

core/common/src/Clock.kt

@@ -12,8 +12,8 @@ import kotlin.time.*
  *
  * See [Clock.System][Clock.System] for the clock instance that queries the operating system.
  *
- * It is recommended not to use [Clock.System] directly in the implementation; instead, one could pass a
- * [Clock] explicitly to the functions or classes that need it.
+ * It is not recommended to use [Clock.System] directly in the implementation. Instead, you can pass a
+ * [Clock] explicitly to the necessary functions or classes.
  * This way, tests can be written deterministically by providing custom [Clock] implementations
  * to the system under test.
  */
@@ -24,7 +24,7 @@ public interface 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,
      * and it must be taken into account.
-     * See the documentation of [Clock.System] for details.
+     * See the [System] documentation for details.
      *
      * Even though [Instant] is defined to be on the UTC-SLS time scale, which enforces a specific way of handling
      * leap seconds, [now] is not guaranteed to handle leap seconds in any specific way.
@@ -38,15 +38,14 @@ public interface Clock {
      * these increases will not necessarily correspond to the elapsed time.
      *
      * For example, when using [Clock.System], the following could happen:
-     * - [now] returns `2023-01-02T22:35:01Z`;
-     * - The system queries the Internet and recognizes that its clock needs adjusting;
+     * - [now] returns `2023-01-02T22:35:01Z`.
+     * - The system queries the Internet and recognizes that its clock needs adjusting.
      * - [now] returns `2023-01-02T22:32:05Z`.
      *
-     * When predictable intervals between successive measurements are needed, consider using
-     * [TimeSource.Monotonic].
+     * When you need predictable intervals between successive measurements, consider using [TimeSource.Monotonic].
      *
-     * For improved testability, one could avoid using [Clock.System] directly in the implementation,
-     * instead passing a [Clock] explicitly. For example:
+     * For improved testability, you should avoid using [Clock.System] directly in the implementation
+     * and pass a [Clock] explicitly instead. For example:
      *
      * @sample kotlinx.datetime.test.samples.ClockSamples.system
      * @sample kotlinx.datetime.test.samples.ClockSamples.dependencyInjection
@@ -74,7 +73,7 @@ public fun Clock.todayIn(timeZone: TimeZone): LocalDate =
 /**
  * Returns a [TimeSource] that uses this [Clock] to mark a time instant and to find the amount of time elapsed since that mark.
  *
- * **Pitfall**: using this function with [Clock.System] is error-prone,
+ * **Pitfall**: using this function with [Clock.System] is error-prone
  * because [Clock.System] is not well suited for measuring time intervals.
  * Please only use this conversion function on the [Clock] instances that are fully controlled programmatically.
  */

core/common/src/DateTimePeriod.kt

@@ -17,10 +17,10 @@ import kotlinx.serialization.Serializable
 /**
  * A difference between two [instants][Instant], decomposed into date and time components.
  *
- * The date components are: [years] ([DateTimeUnit.YEAR]), [months] ([DateTimeUnit.MONTH]), [days] ([DateTimeUnit.DAY]).
+ * The date components are: [years] ([DateTimeUnit.YEAR]), [months] ([DateTimeUnit.MONTH]), and [days] ([DateTimeUnit.DAY]).
  *
  * The time components are: [hours] ([DateTimeUnit.HOUR]), [minutes] ([DateTimeUnit.MINUTE]),
- * [seconds] ([DateTimeUnit.SECOND]), [nanoseconds] ([DateTimeUnit.NANOSECOND]).
+ * [seconds] ([DateTimeUnit.SECOND]), and [nanoseconds] ([DateTimeUnit.NANOSECOND]).
  *
  * The time components are not independent and are always normalized together.
  * Likewise, months are normalized together with years.
@@ -428,7 +428,7 @@ public class DatePeriod internal constructor(
     /**
      * Constructs a new [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 `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,

core/common/src/DateTimeUnit.kt

@@ -20,23 +20,23 @@ import kotlin.time.Duration.Companion.nanoseconds
  *
  * ### Interaction with other entities
  *
- * Any [DateTimeUnit] can be used with [Instant.plus], [Instant.minus] to
+ * Any [DateTimeUnit] can be used with [Instant.plus] or [Instant.minus] to
  * find an instant that is some number of units away from the given instant.
  * Also, [Instant.until] can be used to find the number of the given units between two instants.
  *
- * [DateTimeUnit.TimeBased] can be used in the [Instant] operations without specifying the time zone, because
- * [DateTimeUnit.TimeBased] is defined in terms of passage of real time, and is independent of the time zone.
+ * [DateTimeUnit.TimeBased] can be used in the [Instant] operations without specifying the time zone because
+ * [DateTimeUnit.TimeBased] is defined in terms of the passage of real-time and is independent of the time zone.
  * Note that a calendar day is not considered identical to 24 hours, so using it does require specifying the time zone.
  * See [DateTimeUnit.DayBased] for an explanation.
  *
  * [DateTimeUnit.DateBased] units can be used in the [LocalDate] operations: [LocalDate.plus], [LocalDate.minus], and
  * [LocalDate.until].
  *
  * Arithmetic operations on [LocalDateTime] are not provided.
- * Please see the [LocalDateTime] documentation for a discussion.
+ * Please see the [LocalDateTime] documentation for details.
  *
- * [DateTimePeriod] is a combination of [DateTimeUnit] values of every kind, used to express things like
- * "two days and three hours."
+ * [DateTimePeriod] is a combination of [DateTimeUnit] values of every kind, used to express periods 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 values with different
  * kinds of units, but in exchange, the duration of time between two [Instant] or [LocalDate] values can be
@@ -48,8 +48,8 @@ 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.MICROSECOND * 10`.
- * - By constructing an instance manually with [TimeBased], [DayBased], or [MonthBased]: for example,
+ * - 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_000)`.
  *
  * Also, [DateTimeUnit] can be serialized and deserialized using `kotlinx.serialization`:
@@ -164,8 +164,8 @@ public sealed class DateTimeUnit {
     /**
      * A [date-time 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.
+     * 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`
@@ -204,7 +204,8 @@ public sealed class DateTimeUnit {
     /**
      * A [date-time unit][DateTimeUnit] equal to some number of months.
      *
-     * Since different months have different number of days, a `MonthBased`-unit cannot be expressed as a multiple of some [DayBased]-unit.
+     * 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.
      * @sample kotlinx.datetime.test.samples.DateTimeUnitSamples.monthBasedUnit

core/common/src/Instant.kt

@@ -15,12 +15,12 @@ import kotlin.time.*
 /**
  * A moment in time.
  *
- * A point in time must be uniquely identified, so that it 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 its already `1970-01-01` several hours earlier than someone in
+ * A point in time must be uniquely identified so that it 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].
  * In contrast, "the moment the clocks in London first showed 00:00 on Jan 1, 2000" is a specific moment
- * in time, as is "1970-01-01, 00:00:00 UTC+0", and so it can be represented as an [Instant].
+ * in time, as is "1970-01-01, 00:00:00 UTC+0", so it can be represented as an [Instant].
  *
  * `Instant` uses the UTC-SLS (smeared leap second) time scale. This time scale doesn't contain instants
  * corresponding to leap seconds, but instead "smears" positive and negative leap seconds among the last 1000 seconds
@@ -46,7 +46,7 @@ import kotlin.time.*
  *
  * [Instant] is essentially the number of seconds and nanoseconds since a designated moment in time,
  * stored as something like `1709898983.123456789`.
- * [Instant] contains no information about what day or time it is, as this depends on the time zone.
+ * [Instant] does not contain information about the day or time, as this depends on the time zone.
  * To work with this information for a specific time zone, obtain a [LocalDateTime] using [Instant.toLocalDateTime]:
  *
  * ```
@@ -98,16 +98,16 @@ import kotlin.time.*
  * Since [Instant] represents a point in time, it is always well-defined what the result of arithmetic operations on it
  * is, including the cases when a calendar is used.
  * This is not the case for [LocalDateTime], where the result of arithmetic operations depends on the time zone.
- * See the documentation of [LocalDateTime] for more details.
+ * See the [LocalDateTime] documentation for more details.
  *
  * Adding and subtracting calendar-based units can be done using the [plus] and [minus] operators,
  * requiring a [TimeZone]:
  *
  * ```
- * // one day from now in Berlin
+ * // One day from now in Berlin
  * Clock.System.now().plus(1, DateTimeUnit.DAY, TimeZone.of("Europe/Berlin"))
  *
- * // a day and two hours short from two months later in Berlin
+ * // A day and two hours short from two months later in Berlin
  * Clock.System.now().plus(DateTimePeriod(months = 2, days = -1, hours = -2), TimeZone.of("Europe/Berlin"))
  * ```
  *
@@ -118,7 +118,7 @@ import kotlin.time.*
  * val start = Clock.System.now()
  * val concertStart = LocalDateTime(2023, 1, 1, 20, 0, 0).toInstant(TimeZone.of("Europe/Berlin"))
  * val timeUntilConcert = start.periodUntil(concertStart, TimeZone.of("Europe/Berlin"))
- * // two months, three days, four hours, and five minutes until the concert
+ * // Two months, three days, four hours, and five minutes until the concert
  * ```
  *
  * or [Instant.until] method, as well as [Instant.daysUntil], [Instant.monthsUntil],
@@ -187,7 +187,7 @@ import kotlin.time.*
  * ```
  *
  * Additionally, there are several `kotlinx-serialization` serializers for [Instant]:
- * - [InstantIso8601Serializer] for the ISO 8601 extended format,
+ * - [InstantIso8601Serializer] for the ISO 8601 extended format.
  * - [InstantComponentSerializer] for an object with components.
  *
  * @see LocalDateTime for a user-visible representation of moments in time in an unspecified time zone.
@@ -285,7 +285,7 @@ public expect class Instant : Comparable<Instant> {
 
     /**
      * Compares `this` instant with the [other] instant.
-     * Returns zero if this instant represents the same moment as the other (i.e., equal to other),
+     * Returns zero if this instant represents the same moment as the other (i.e., when it's equal to other),
      * a negative number if this instant is earlier than the other,
      * and a positive number if this instant is later than the other.
      *
@@ -294,9 +294,9 @@ public expect class Instant : Comparable<Instant> {
     public override operator fun compareTo(other: Instant): Int
 
     /**
-     * Converts this instant to the ISO 8601 string representation; for example, `2023-01-02T23:40:57.120Z`
+     * Converts this instant to the ISO 8601 string representation, for example, `2023-01-02T23:40:57.120Z`.
      *
-     * The representation uses the UTC-SLS time scale, instead of UTC.
+     * The representation uses the UTC-SLS time scale instead of UTC.
      * In practice, this means that leap second handling will not be readjusted to the UTC.
      * Leap seconds will not be added or skipped, so it is impossible to acquire a string
      * where the component for seconds is 60, and for any day, it's possible to observe 23:59:59.
@@ -480,9 +480,9 @@ public fun Instant.minus(period: DateTimePeriod, timeZone: TimeZone): Instant =
  * The components of [DateTimePeriod] are calculated so that adding it to `this` instant results in the [other] instant.
  *
  * All components of the [DateTimePeriod] returned are:
- * - positive or zero if this instant is earlier than the other,
- * - negative or zero if this instant is later than the other,
- * - exactly zero if this instant is equal to the other.
+ * - Positive or zero if this instant is earlier than the other.
+ * - Negative or zero if this instant is later than the other.
+ * - Exactly zero if this instant is equal to the other.
  *
  * @throws DateTimeArithmeticException if `this` or [other] instant is too large to fit in [LocalDateTime].
  *     Or (only on the JVM) if the number of months between the two dates exceeds an Int.
@@ -495,9 +495,9 @@ public expect fun Instant.periodUntil(other: Instant, timeZone: TimeZone): DateT
  * in the specified [timeZone].
  *
  * The value returned is:
- * - positive or zero if this instant is earlier than the other,
- * - negative or zero if this instant is later than the other,
- * - zero if this instant is equal to the other.
+ * - Positive or zero if this instant is earlier than the other.
+ * - Negative or zero if this instant is later than the other.
+ * - Zero if this instant is equal to the other.
  *
  * If the result does not fit in [Long], returns [Long.MAX_VALUE] for a positive result or [Long.MIN_VALUE] for a negative result.
  *
@@ -510,9 +510,9 @@ public expect fun Instant.until(other: Instant, unit: DateTimeUnit, timeZone: Ti
  * Returns the whole number of the specified time [units][unit] between `this` and [other] instants.
  *
  * The value returned is:
- * - positive or zero if this instant is earlier than the other,
- * - negative or zero if this instant is later than the other,
- * - zero if this instant is equal to the other.
+ * - Positive or zero if this instant is earlier than the other.
+ * - Negative or zero if this instant is later than the other.
+ * - Zero if this instant is equal to the other.
  *
  * If the result does not fit in [Long], returns [Long.MAX_VALUE] for a positive result or [Long.MIN_VALUE] for a negative result.
  *
@@ -570,9 +570,9 @@ public fun Instant.yearsUntil(other: Instant, timeZone: TimeZone): Int =
  * The components of [DateTimePeriod] are calculated so that adding it back to the `other` instant results in this instant.
  *
  * All components of the [DateTimePeriod] returned are:
- * - negative or zero if this instant is earlier than the other,
- * - positive or zero if this instant is later than the other,
- * - exactly zero if this instant is equal to the other.
+ * - Negative or zero if this instant is earlier than the other.
+ * - Positive or zero if this instant is later than the other.
+ * - Exactly zero if this instant is equal to the other.
  *
  * @throws DateTimeArithmeticException if `this` or [other] instant is too large to fit in [LocalDateTime].
  *   Or (only on the JVM) if the number of months between the two dates exceeds an Int.