Add documentation for common methods

Author: ilya-g

core/commonMain/src/Instant.kt

@@ -11,145 +11,291 @@ import kotlin.time.ExperimentalTime
 @OptIn(ExperimentalTime::class)
 public expect class Instant : Comparable<Instant> {
 
-    /** */
+    /**
+     * The number of seconds from the epoch instant `1970-01-01T00:00:00Z` rounded down to a [Long] number.
+     *
+     * The difference between the rounded number of seconds and the actual number of seconds
+     * is returned by [nanosecondsOfSecond] property expressed in nanoseconds.
+     *
+     * @see Instant.fromEpochSeconds
+     */
     public val epochSeconds: Long
 
-    /** */
+    /**
+     * The number of nanoseconds by which this instant is later than [epochSeconds] from the epoch instant.
+     *
+     * The value is always positive and lies in the range `0..999_999_999`.
+     *
+     * @see Instant.fromEpochSeconds
+     */
     public val nanosecondsOfSecond: Int
 
     /**
-     * The return value is clamped to [Long.MAX_VALUE] or [Long.MIN_VALUE] if the result does not fit in [Long].
+     * Returns the number of milliseconds from the epoch instant `1970-01-01T00:00:00Z`.
+     *
+     * Any fractional part of millisecond is rounded down 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.
+     *
+     * @see Instant.fromEpochMilliseconds
      */
     public fun toEpochMilliseconds(): Long
 
     /**
+     * Returns an instant that is the result of adding the specified [duration] to this instant.
+     *
+     * If the [duration] is positive, the returned instant is later than this instant.
+     * If the [duration] is negative, the returned instant is earlier than this instant.
+     *
      * The return value is clamped to the platform-specific boundaries for [Instant] if the result exceeds them.
      */
     @ExperimentalTime
     public operator fun plus(duration: Duration): Instant
 
     /**
+     * Returns an instant that is the result of subtracting the specified [duration] from this instant.
+     *
+     * If the [duration] is positive, the returned instant is earlier than this instant.
+     * If the [duration] is negative, the returned instant is later than this instant.
+     *
      * The return value is clamped to the platform-specific boundaries for [Instant] if the result exceeds them.
      */
     @ExperimentalTime
     public operator fun minus(duration: Duration): Instant
 
     // questionable
-    /** */
+    /**
+     * Returns the [Duration] between two instants: [other] and `this`.
+     *
+     * The duration returned is positive if this instant is later than the other,
+     * and negative if this instant is earlier than the other.
+     *
+     * The result is never clamped, but note that for instants that are far apart,
+     * the value returned may represent the duration between them inexactly due to the loss of precision.
+     */
     @ExperimentalTime
     public operator fun minus(other: Instant): Duration
 
-    /** */
+    /**
+     * Compares `this` instant with the [other] instant.
+     * Returns zero if this instant represent the same moment as the other (i.e. 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.
+     */
     public override operator fun compareTo(other: Instant): Int
 
+    /**
+     * Converts this instant to the ISO-8601 string representation.
+     *
+     * @see Instant.parse
+     */
+    public override fun toString(): String
+
+
     companion object {
-        /** */
         @Deprecated("Use Clock.System.now() instead", ReplaceWith("Clock.System.now()", "kotlinx.datetime.Clock"), level = DeprecationLevel.ERROR)
         fun now(): Instant
 
         /**
+         * Returns an [Instant] that is [epochMilliseconds] number of milliseconds from the epoch instant `1970-01-01T00:00:00Z`.
+         *
          * The return value is clamped to the platform-specific boundaries for [Instant] if the result exceeds them.
          */
         fun fromEpochMilliseconds(epochMilliseconds: Long): Instant
 
         /**
+         * Returns an [Instant] that is the [epochSeconds] number of seconds from the epoch instant `1970-01-01T00:00:00Z`
+         * and the [nanosecondAdjustment] number of nanoseconds from the whole second.
+         *
          * The return value is clamped to the platform-specific boundaries for [Instant] if the result exceeds them.
          */
         fun fromEpochSeconds(epochSeconds: Long, nanosecondAdjustment: Long = 0): Instant
 
         /**
+         * Parses a string that represents an instant in ISO-8601 format including date and time components and
+         * the mandatory `Z` designator of the UTC+0 time zone and returns the parsed [Instant] value.
+         *
+         * Examples of instants in ISO-8601 format:
+         * - `2020-08-30T18:43:00Z`
+         * - `2020-08-30T18:43:00.500Z`
+         * - `2020-08-30T18:43:00.123456789Z`
+         *
          * @throws DateTimeFormatException if the text cannot be parsed or the boundaries of [Instant] are exceeded.
          */
         fun parse(isoString: String): Instant
 
-        // -100001-12-31T23:59:59.999999999Z
-        val DISTANT_PAST: Instant
 
-        // +100000-01-01T00:00:00Z
-        val DISTANT_FUTURE: Instant
+        /**
+         * An instant value that is far in the past.
+         *
+         * All instants in the range `DISTANT_PAST..DISTANT_FUTURE` can be converted to [LocalDateTime][Instant.toLocalDateTime]
+         * without exceptions on all supported platforms.
+         */
+        val DISTANT_PAST: Instant // -100001-12-31T23:59:59.999999999Z
+
+        /**
+         * An instant value that is far in the future.
+         *
+         * All instants in the range `DISTANT_PAST..DISTANT_FUTURE` can be converted to [LocalDateTime][Instant.toLocalDateTime]
+         * without exceptions on all supported platforms.
+         */
+        val DISTANT_FUTURE: Instant // +100000-01-01T00:00:00Z
 
         internal val MIN: Instant
         internal val MAX: Instant
     }
 }
 
+/** Returns true if the instant is not later than [Instant.DISTANT_PAST]. */
 public val Instant.isDistantPast
     get() = this <= Instant.DISTANT_PAST
 
+/** Returns true if the instant is not earlier than [Instant.DISTANT_FUTURE]. */
 public val Instant.isDistantFuture
     get() = this >= Instant.DISTANT_FUTURE
 
 /**
+ * Converts this string representing an instant in ISO-8601 format including date and time components and
+ * the mandatory `Z` designator of the UTC+0 time zone to an [Instant] value.
+ *
+ * See [Instant.parse] for examples of instant string representations.
+ *
  * @throws DateTimeFormatException if the text cannot be parsed or the boundaries of [Instant] are exceeded.
  */
 public fun String.toInstant(): Instant = Instant.parse(this)
 
 /**
+ * Returns an instant that is the result of adding components of [DateTimePeriod] to this instant. The components are
+ * added in the order from the largest units to the smallest, i.e. from years to nanoseconds.
+ *
  * @throws DateTimeArithmeticException if this value or the results of intermediate computations are too large to fit in
  * [LocalDateTime].
  */
 public expect fun Instant.plus(period: DateTimePeriod, timeZone: TimeZone): Instant
 
 /**
- * @throws DateTimeArithmeticException if this [Instant] or [other] is too large to fit in [LocalDateTime].
+ * Returns a [DateTimePeriod] representing the difference between `this` and [other] instants.
+ *
+ * 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.
+ *
+ * @throws DateTimeArithmeticException if `this` or [other] instant is too large to fit in [LocalDateTime].
  */
 public expect fun Instant.periodUntil(other: Instant, timeZone: TimeZone): DateTimePeriod
 
 /**
- * The return value is clamped to [Long.MAX_VALUE] or [Long.MIN_VALUE] if [unit] is more granular than
- * [DateTimeUnit.DAY] and the result is too large.
+ * Returns the whole number of the specified date or time [units][unit] between `this` and [other] instants
+ * in the specified [timeZone].
  *
- * @throws DateTimeArithmeticException if this [Instant] or [other] is too large to fit in [LocalDateTime].
+ * 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.
+
+ * If the result does not fit in [Long], returns [Long.MAX_VALUE] for a positive result or [Long.MIN_VALUE] for a negative result.
+ *
+ * @throws DateTimeArithmeticException if `this` or [other] instant is too large to fit in [LocalDateTime].
  */
 public expect fun Instant.until(other: Instant, unit: DateTimeUnit, timeZone: TimeZone): Long
 
 /**
- * The return value is clamped to [Int.MAX_VALUE] or [Int.MIN_VALUE] if the result would otherwise cause an arithmetic
- * overflow.
+ * Returns the number of whole days between two instants in the specified [timeZone].
+ *
+ * If the result does not fit in [Int], returns [Int.MAX_VALUE] for a positive result or [Int.MIN_VALUE] for a negative result.
  *
- * @throws DateTimeArithmeticException if this [Instant] or [other] is too large to fit in [LocalDateTime].
+ * @see Instant.until
+ * @throws DateTimeArithmeticException if `this` or [other] instant is too large to fit in [LocalDateTime].
  */
 public fun Instant.daysUntil(other: Instant, timeZone: TimeZone): Int =
         until(other, DateTimeUnit.DAY, timeZone).clampToInt()
 
 /**
- * The return value is clamped to [Int.MAX_VALUE] or [Int.MIN_VALUE] if the result would otherwise cause an arithmetic
- * overflow.
+ * Returns the number of whole months between two instants in the specified [timeZone].
  *
- * @throws DateTimeArithmeticException if this [Instant] or [other] is too large to fit in [LocalDateTime].
+ * 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 Instant.until
+ * @throws DateTimeArithmeticException if `this` or [other] instant is too large to fit in [LocalDateTime].
  */
 public fun Instant.monthsUntil(other: Instant, timeZone: TimeZone): Int =
         until(other, DateTimeUnit.MONTH, timeZone).clampToInt()
 
 /**
- * The return value is clamped to [Int.MAX_VALUE] or [Int.MIN_VALUE] if the result would otherwise cause an arithmetic
- * overflow.
+ * Returns the number of whole years between two instants in the specified [timeZone].
+ *
+ * If the result does not fit in [Int], returns [Int.MAX_VALUE] for a positive result or [Int.MIN_VALUE] for a negative result.
  *
- * @throws DateTimeArithmeticException if this [Instant] or [other] is too large to fit in [LocalDateTime].
+ * @see Instant.until
+ * @throws DateTimeArithmeticException if `this` or [other] instant is too large to fit in [LocalDateTime].
  */
 public fun Instant.yearsUntil(other: Instant, timeZone: TimeZone): Int =
         until(other, DateTimeUnit.YEAR, timeZone).clampToInt()
 
+/**
+ * Returns a [DateTimePeriod] representing the difference between [other] and `this` instants.
+ *
+ * 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.
+ *
+ * @throws DateTimeArithmeticException if `this` or [other] instant is too large to fit in [LocalDateTime].
+ * @see Instant.periodUntil
+ */
 public fun Instant.minus(other: Instant, timeZone: TimeZone): DateTimePeriod =
         other.periodUntil(this, timeZone)
 
 
 /**
+ * Returns an instant that is the result of adding one [unit] to this instant
+ * in the specified [timeZone].
+ *
+ * The returned instant is later than this instant.
+ *
  * @throws DateTimeArithmeticException if this value or the result is too large to fit in [LocalDateTime].
  */
 public expect fun Instant.plus(unit: DateTimeUnit, timeZone: TimeZone): Instant
 
 /**
+ * Returns an instant that is the result of adding the [value] number of the specified [unit] to this instant
+ * in the specified [timeZone].
+ *
+ * If the [value] is positive, the returned instant is later than this instant.
+ * If the [value] is negative, the returned instant is earlier than this instant.
+ *
  * @throws DateTimeArithmeticException if this value or the result is too large to fit in [LocalDateTime].
  */
 public expect fun Instant.plus(value: Int, unit: DateTimeUnit, timeZone: TimeZone): Instant
 
 /**
+ * Returns an instant that is the result of adding the [value] number of the specified [unit] to this instant
+ * in the specified [timeZone].
+ *
+ * If the [value] is positive, the returned instant is later than this instant.
+ * If the [value] is negative, the returned instant is earlier than this instant.
+ *
  * @throws DateTimeArithmeticException if this value or the result is too large to fit in [LocalDateTime].
  */
 public expect fun Instant.plus(value: Long, unit: DateTimeUnit, timeZone: TimeZone): Instant
 
-
+/**
+ * Returns the whole number of the specified date or time [units][unit] between [other] and `this` instants
+ * in the specified [timeZone].
+ *
+ * The value returned is negative or zero if this instant is earlier than the other,
+ * and positive or zero if this instant is later than 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.
+ *
+ * @throws DateTimeArithmeticException if `this` or [other] instant is too large to fit in [LocalDateTime].
+ * @see Instant.until
+ */
 public fun Instant.minus(other: Instant, unit: DateTimeUnit, timeZone: TimeZone): Long =
         other.until(this, unit, timeZone)