Fix typos and small mistakes

Author: dkhalanskyjb

core/common/src/DateTimePeriod.kt

@@ -39,7 +39,7 @@ import kotlinx.serialization.Serializable
  * [parse] and [toString] methods can be used to obtain a [DateTimePeriod] from and convert it to a string in the
  * ISO 8601 extended format (for example, `P1Y2M6DT13H`).
  *
- * or returned as the result of instant arithmetic operations (see [Instant.periodUntil]).
+ * `DateTimePeriod` can also be returned as the result of instant arithmetic operations (see [Instant.periodUntil]).
  *
  * Additionally, there are several `kotlinx-serialization` serializers for [DateTimePeriod]:
  * - [DateTimePeriodIso8601Serializer] for the ISO 8601 format;
@@ -54,7 +54,7 @@ public sealed class DateTimePeriod {
      * The number of calendar days.
      *
      * Note that a calendar day is not identical to 24 hours, see [DateTimeUnit.DayBased] for details.
-     * Also, this field does not overflow into months, so values larger than 30 can be present.
+     * Also, this field does not overflow into months, so values larger than 31 can be present.
      */
     public abstract val days: Int
     internal abstract val totalNanoseconds: Long

core/common/src/Instant.kt

@@ -38,16 +38,16 @@ 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,
  * so it should not be used for measuring time intervals.
- * For measuring time intervals, consider [TimeSource.Monotonic].
+ * For that, consider [TimeSource.Monotonic].
  *
  * ### Obtaining human-readable representations
  *
  * #### Date and time
  *
- * [Instant] is essentially the number of seconds and nanoseconds since a deesignated moment in 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.
- * To obtain this information for a specific time zone, obtain a [LocalDateTime] using [Instant.toLocalDateTime]:
+ * To work with this information for a specific time zone, obtain a [LocalDateTime] using [Instant.toLocalDateTime]:
  *
  * ```
  * val instant = Instant.fromEpochSeconds(1709898983, 123456789)
@@ -57,11 +57,11 @@ import kotlin.time.*
  *
  * For values very far in the past or the future, this conversion may fail.
  * The specific range of values that can be converted to [LocalDateTime] is platform-specific, but at least
- * [DISTANT_PAST], [DISTANT_FUTURE], and all values between them can be converted to [LocalDateTime] without exceptions.
+ * [DISTANT_PAST], [DISTANT_FUTURE], and all values between them can be converted to [LocalDateTime].
  *
  * #### Date or time separately
  *
- * To obtain a [LocalDate] or [LocalTime], first, obtain a [LocalDateTime] and then use its [LocalDateTime.date]
+ * To obtain a [LocalDate] or [LocalTime], first, obtain a [LocalDateTime], and then use its [LocalDateTime.date]
  * and [LocalDateTime.time] properties:
  *
  * ```
@@ -73,7 +73,7 @@ import kotlin.time.*
  *
  * #### Elapsed-time-based
  *
- * The [plus] and [minus] operators can be used to add and subtract [Duration]s from an [Instant]:
+ * 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
@@ -85,7 +85,7 @@ import kotlin.time.*
  * Clock.System.now().plus(4, DateTimeUnit.HOUR) // 4 hours from now
  * ```
  *
- * Also, there is a [minus] operator that returns a [Duration] representing the difference between two instants:
+ * Also, there is a [minus] operator that returns the [Duration] representing the difference between two instants:
  *
  * ```
  * val start = Clock.System.now()
@@ -137,7 +137,7 @@ import kotlin.time.*
  * [toEpochMilliseconds] can be used to obtain the number of milliseconds since the epoch.
  * Note that [Instant] supports nanosecond precision, so converting to milliseconds is a lossy operation.
  *
- * [parse] and [toString] methods can be used to obtain a [Instant] from and convert it to a string in the
+ * [parse] and [toString] methods can be used to obtain an [Instant] from and convert it to a string in the
  * ISO 8601 extended format (for example, `2023-01-02T22:35:01+01:00`).
  * During parsing, the UTC offset is not returned separately.
  * If the UTC offset is important, use [DateTimeComponents] with [DateTimeComponents.Formats.ISO_DATE_TIME_OFFSET] to
@@ -210,8 +210,7 @@ public expect class Instant : Comparable<Instant> {
      * **Pitfall**: do not use [Duration] values obtained via [Duration.Companion.days], as this is misleading:
      * in `kotlinx-datetime`, adding a day is a calendar-based operation, whereas [Duration] always considers
      * a day to be 24 hours.
-     * For an explanation of why this is error-prone, see the section about arithmetic operations in the [LocalDateTime]
-     * documentation.
+     * For an explanation of why this is error-prone, see [DateTimeUnit.DayBased].
      */
     public operator fun minus(duration: Duration): Instant
 

core/common/src/LocalDateTime.kt

@@ -28,7 +28,7 @@ import kotlinx.serialization.Serializable
  * The arithmetic on [LocalDateTime] values is not provided, since without accounting for the time zone transitions it
  * may give misleading results.
  *
- * For example, in Berlin, naively adding one day to `2021-03-28T02:16:20` without accounting for the time zone would
+ * 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.
  * This is known as a "time gap", or a "spring forward" transition.

core/common/src/TimeZone.kt

@@ -15,7 +15,7 @@ import kotlinx.serialization.Serializable
  * A time zone, provides the conversion between [Instant] and [LocalDateTime] values
  * using a collection of rules specifying which [LocalDateTime] value corresponds to each [Instant].
  *
- * A time zone needs can be used in [Instant.toLocalDateTime] and [LocalDateTime.toInstant], and also in
+ * A time zone can be used in [Instant.toLocalDateTime] and [LocalDateTime.toInstant], and also in
  * those arithmetic operations on [Instant] that require knowing the calendar.
  *
  * A [TimeZone] can be constructed using the [TimeZone.of] function, which accepts the string identifier, like

core/common/src/format/DateTimeComponents.kt

@@ -90,7 +90,7 @@ public class DateTimeComponents internal constructor(internal val contents: Date
          * ISO 8601 extended format for dates and times with UTC offset.
          *
          * For specifying the time zone offset, the format uses the [UtcOffset.Formats.ISO] format, except that during
-         * parsing, specifying the minutes is optional.
+         * parsing, specifying the minutes of the offset is optional.
          *
          * This format differs from [LocalTime.Formats.ISO] in its time part in that
          * specifying the seconds is *not* optional.