More samples; only LocalDate and Instant left

Author: dkhalanskyjb

core/common/src/DateTimeUnit.kt

@@ -56,18 +56,17 @@ import kotlin.time.Duration.Companion.nanoseconds
  * [DateTimeUnitSerializer], [DateBasedDateTimeUnitSerializer], [DayBasedDateTimeUnitSerializer],
  * [MonthBasedDateTimeUnitSerializer], and [TimeBasedDateTimeUnitSerializer] are provided, with varying levels of
  * specificity of the type they handle.
+ *
+ * @sample kotlinx.datetime.test.samples.DateTimeUnitSamples.construction
  */
 @Serializable(with = DateTimeUnitSerializer::class)
 public sealed class DateTimeUnit {
 
     /**
      * Produces a date-time unit that is a multiple of this unit times the specified integer [scalar] value.
      *
-     * ```
-     * val quarter = DateTimeUnit.MONTH * 3
-     * ```
-     *
      * @throws ArithmeticException if the result overflows.
+     * @sample kotlinx.datetime.test.samples.DateTimeUnitSamples.multiplication
      */
     public abstract operator fun times(scalar: Int): DateTimeUnit
 
@@ -78,11 +77,14 @@ public sealed class DateTimeUnit {
      * Any such unit can be represented as some fixed number of nanoseconds.
      *
      * @see DateTimeUnit for a description of date-time units in general.
+     * @sample kotlinx.datetime.test.samples.DateTimeUnitSamples.timeBasedUnit
      */
     @Serializable(with = TimeBasedDateTimeUnitSerializer::class)
     public class TimeBased(
         /**
          * The length of this unit in nanoseconds.
+         *
+         * @sample kotlinx.datetime.test.samples.DateTimeUnitSamples.timeBasedUnit
          */
         public val nanoseconds: Long
     ) : DateTimeUnit() {
@@ -124,6 +126,8 @@ public sealed class DateTimeUnit {
 
         /**
          * The length of this unit as a [Duration].
+         *
+         * @sample kotlinx.datetime.test.samples.DateTimeUnitSamples.timeBasedUnit
          */
         public val duration: Duration
             get() = nanoseconds.nanoseconds
@@ -144,6 +148,8 @@ public sealed class DateTimeUnit {
      * the operation with the date component of these `LocalDateTime` values.
      *
      * @see DateTimeUnit for a description of date-time units in general.
+     * @see DateTimeUnit.DayBased for specifically day-based units.
+     * @see DateTimeUnit.MonthBased for specifically month-based units.
      */
     @Serializable(with = DateBasedDateTimeUnitSerializer::class)
     public sealed class DateBased : DateTimeUnit() {
@@ -167,11 +173,14 @@ public sealed class DateTimeUnit {
      * between the two date-times.
      *
      * @see DateTimeUnit for a description of date-time units in general.
+     * @sample kotlinx.datetime.test.samples.DateTimeUnitSamples.dayBasedUnit
      */
     @Serializable(with = DayBasedDateTimeUnitSerializer::class)
     public class DayBased(
         /**
          * The length of this unit in days.
+         *
+         * @sample kotlinx.datetime.test.samples.DateTimeUnitSamples.dayBasedUnit
          */
         public val days: Int
     ) : DateBased() {
@@ -198,11 +207,14 @@ public sealed class DateTimeUnit {
      * Since different months have different number of days, a `MonthBased`-unit cannot be expressed a multiple of some [DayBased]-unit.
      *
      * @see DateTimeUnit for a description of date-time units in general.
+     * @sample kotlinx.datetime.test.samples.DateTimeUnitSamples.monthBasedUnit
      */
     @Serializable(with = MonthBasedDateTimeUnitSerializer::class)
     public class MonthBased(
         /**
          * The length of this unit in months.
+         *
+         * @sample kotlinx.datetime.test.samples.DateTimeUnitSamples.monthBasedUnit
          */
         public val months: Int
     ) : DateBased() {

core/common/src/DayOfWeek.kt

@@ -10,6 +10,8 @@ package kotlinx.datetime
  *
  * Usually acquired from [LocalDate.dayOfWeek], but can be constructed using the `DayOfWeek` factory function that
  * accepts the ISO 8601 day number. This number can be obtained from the [isoDayNumber] property.
+ *
+ * @sample kotlinx.datetime.test.samples.DayOfWeekSamples.usage
  */
 public expect enum class DayOfWeek {
     MONDAY,
@@ -23,13 +25,16 @@ public expect enum class DayOfWeek {
 
 /**
  * The ISO 8601 number of the given day of the week. Monday is 1, Sunday is 7.
+ *
+ * @sample kotlinx.datetime.test.samples.DayOfWeekSamples.isoDayNumber
  */
 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.
  *
  * @throws IllegalArgumentException if the day number is not in the range 1..7
+ * @sample kotlinx.datetime.test.samples.DayOfWeekSamples.constructorFunction
  */
 public fun DayOfWeek(isoDayNumber: Int): DayOfWeek {
     require(isoDayNumber in 1..7) { "Expected ISO day-of-week number in 1..7, got $isoDayNumber" }

core/common/src/LocalDateTime.kt

@@ -69,41 +69,18 @@ import kotlinx.serialization.Serializable
  * The recommended pattern is to convert a [LocalDateTime] to [Instant] as soon as possible (see
  * [LocalDateTime.toInstant]) and work with [Instant] values instead.
  *
- * [LocalDateTime] can be constructed directly from its components, [LocalDate] and [LocalTime], using the constructor:
- *
- * ```
- * val date = LocalDate(2021, 3, 27)
- * val time = LocalTime(hour = 2, minute = 16, second = 20)
- * LocalDateTime(date, time)
- * ```
+ * [LocalDateTime] can be constructed directly from its components, [LocalDate] and [LocalTime], using the constructor.
+ * See sample 1.
  *
  * Some additional constructors that accept the date's and time's fields directly are provided for convenience.
- *
- * ```
- * LocalDateTime(year = 2021, monthNumber = 3, dayOfMonth = 27, hour = 2, minute = 16, second = 20)
- * LocalDateTime(
- *     year = 2021, month = Month.MARCH, dayOfMonth = 27,
- *     hour = 2, minute = 16, second = 20, nanosecond = 999_999_999
- * )
- * ```
+ * See sample 2.
  *
  * [parse] and [toString] methods can be used to obtain a [LocalDateTime] from and convert it to a string in the
  * ISO 8601 extended format (for example, `2023-01-02T22:35:01`).
- *
- * ```
- * LocalDateTime.parse("2023-01-02T22:35:01").toString() // 2023-01-02T22:35:01
- * ```
+ * See sample 3.
  *
  * [parse] and [LocalDateTime.format] both support custom formats created with [Format] or defined in [Formats].
- *
- * ```
- * val customFormat = LocalDateTime.Format {
- *    date(LocalDate.Formats.ISO)
- *    char(' ')
- *    time(LocalTime.Formats.ISO)
- * }
- * LocalDateTime.parse("2023-01-02 22:35:01", customFormat).format(customFormat) // 2023-01-02 22:35:01
- * ```
+ * See sample 4.
  *
  * Additionally, there are several `kotlinx-serialization` serializers for [LocalDateTime]:
  * - [LocalDateTimeIso8601Serializer] for the ISO 8601 extended format,
@@ -112,6 +89,10 @@ import kotlinx.serialization.Serializable
  * @see LocalDate for only the date part of the date/time value.
  * @see LocalTime for only the time part of the date/time value.
  * @see Instant for the representation of a specific moment in time independent of a time zone.
+ * @sample kotlinx.datetime.test.samples.LocalDateTimeSamples.fromDateAndTime
+ * @sample kotlinx.datetime.test.samples.LocalDateTimeSamples.alternativeConstruction
+ * @sample kotlinx.datetime.test.samples.LocalDateTimeSamples.simpleParsingAndFormatting
+ * @sample kotlinx.datetime.test.samples.LocalDateTimeSamples.customFormat
  */
 @Serializable(with = LocalDateTimeIso8601Serializer::class)
 public expect class LocalDateTime : Comparable<LocalDateTime> {
@@ -130,6 +111,8 @@ public expect class LocalDateTime : Comparable<LocalDateTime> {
          *
          * @throws IllegalArgumentException if the text cannot be parsed or the boundaries of [LocalDateTime] are
          * exceeded.
+         *
+         * @sample kotlinx.datetime.test.samples.LocalDateTimeSamples.parsing
          */
         public fun parse(input: CharSequence, format: DateTimeFormat<LocalDateTime> = getIsoDateTimeFormat()): LocalDateTime
 
@@ -156,6 +139,8 @@ public expect class LocalDateTime : Comparable<LocalDateTime> {
          * There is a collection of predefined formats in [LocalDateTime.Formats].
          *
          * @throws IllegalArgumentException if parsing using this format is ambiguous.
+         *
+         * @sample kotlinx.datetime.test.samples.LocalDateTimeSamples.customFormat
          */
         @Suppress("FunctionName")
         public fun Format(builder: DateTimeFormatBuilder.WithDateTime.() -> Unit): DateTimeFormat<LocalDateTime>
@@ -186,6 +171,8 @@ public expect class LocalDateTime : Comparable<LocalDateTime> {
          * Fractional parts of the second are included if non-zero.
          *
          * Guaranteed to parse all strings that [LocalDateTime.toString] produces.
+         *
+         * @sample kotlinx.datetime.test.samples.LocalDateTimeSamples.Formats.iso
          */
         public val ISO: DateTimeFormat<LocalDateTime>
     }
@@ -207,6 +194,8 @@ public expect class LocalDateTime : Comparable<LocalDateTime> {
      *
      * @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
      */
     public constructor(
         year: Int,
@@ -233,6 +222,8 @@ public expect class LocalDateTime : Comparable<LocalDateTime> {
      *
      * @throws IllegalArgumentException if any parameter is out of range,
      * or if [dayOfMonth] is invalid for the given [month] and [year].
+     *
+     * @sample kotlinx.datetime.test.samples.LocalDateTimeSamples.constructorFunction
      */
     public constructor(
         year: Int,
@@ -246,43 +237,93 @@ public expect class LocalDateTime : Comparable<LocalDateTime> {
 
     /**
      * Constructs a [LocalDateTime] instance by combining the given [date] and [time] parts.
+     *
+     * @sample kotlinx.datetime.test.samples.LocalDateTimeSamples.fromDateAndTime
      */
     public constructor(date: LocalDate, time: LocalTime)
 
-    /** Returns the year component of the date. */
+    /**
+     * Returns the year component of the [date]. Can be negative.
+     *
+     * @sample kotlinx.datetime.test.samples.LocalDateTimeSamples.dateComponents
+     */
     public val year: Int
 
-    /** Returns the number-of-the-month (1..12) component of the date. */
+    /**
+     * Returns the number-of-the-month (1..12) component of the [date].
+     *
+     * @sample kotlinx.datetime.test.samples.LocalDateTimeSamples.dateComponents
+     */
     public val monthNumber: Int
 
-    /** Returns the month ([Month]) component of the date. */
+    /**
+     * Returns the month ([Month]) component of the [date].
+     *
+     * @sample kotlinx.datetime.test.samples.LocalDateTimeSamples.dateComponents
+     */
     public val month: Month
 
-    /** Returns the day-of-month component of the date. */
+    /**
+     * Returns the day-of-month (`1..31`) component of the [date].
+     *
+     * @sample kotlinx.datetime.test.samples.LocalDateTimeSamples.dateComponents
+     */
     public val dayOfMonth: Int
 
-    /** Returns the day-of-week component of the date. */
+    /**
+     * Returns the day-of-week component of the [date].
+     *
+     * @sample kotlinx.datetime.test.samples.LocalDateTimeSamples.dateComponents
+     */
     public val dayOfWeek: DayOfWeek
 
-    /** Returns the 1-based day-of-year component of the date. */
+    /**
+     * Returns the 1-based day-of-year component of the [date].
+     *
+     * @sample kotlinx.datetime.test.samples.LocalDateTimeSamples.dateComponents
+     */
     public val dayOfYear: Int
 
-    /** Returns the hour-of-day time component of this date/time value. */
+    /**
+     * Returns the hour-of-day (`0..59`) [time] component of this date/time value.
+     *
+     * @sample kotlinx.datetime.test.samples.LocalDateTimeSamples.timeComponents
+     */
     public val hour: Int
 
-    /** Returns the minute-of-hour time component of this date/time value. */
+    /**
+     * Returns the minute-of-hour (`0..59`) [time] component of this date/time value.
+     *
+     * @sample kotlinx.datetime.test.samples.LocalDateTimeSamples.timeComponents
+     */
     public val minute: Int
 
-    /** Returns the second-of-minute time component of this date/time value. */
+    /**
+     * Returns the second-of-minute (`0..59`) [time] component of this date/time value.
+     *
+     * @sample kotlinx.datetime.test.samples.LocalDateTimeSamples.timeComponents
+     */
     public val second: Int
 
-    /** Returns the nanosecond-of-second time component of this date/time value. */
+    /**
+     * Returns the nanosecond-of-second (`0..999_999_999`) [time] component of this date/time value.
+     *
+     * @sample kotlinx.datetime.test.samples.LocalDateTimeSamples.timeComponents
+     */
     public val nanosecond: Int
 
-    /** Returns the date part of this date/time value. */
+    /**
+     * Returns the date part of this date/time value.
+     *
+     * @sample kotlinx.datetime.test.samples.LocalDateTimeSamples.dateAndTime
+     */
     public val date: LocalDate
 
-    /** Returns the time part of this date/time value. */
+    /**
+     * Returns the time part of this date/time value.
+     *
+     * @sample kotlinx.datetime.test.samples.LocalDateTimeSamples.dateAndTime
+     */
     public val time: LocalTime
 
     /**
@@ -300,6 +341,8 @@ public expect class LocalDateTime : Comparable<LocalDateTime> {
      * val ldt2 = Clock.System.now().toLocalDateTime(zone) // 2021-10-31T02:01:20
      * ldt2 > ldt1 // returns `false`
      * ```
+     *
+     * @sample kotlinx.datetime.test.samples.LocalDateTimeSamples.compareToSample
      */
     public override operator fun compareTo(other: LocalDateTime): Int
 
@@ -321,6 +364,7 @@ public expect class LocalDateTime : Comparable<LocalDateTime> {
      * even if they are zero, and will not add trailing zeros to the fractional part of the second for readability.
      * @see parse for the dual operation: obtaining [LocalDateTime] from a string.
      * @see LocalDateTime.format for formatting using a custom format.
+     * @sample kotlinx.datetime.test.samples.LocalDateTimeSamples.toStringSample
      */
     public override fun toString(): String
 }
@@ -330,6 +374,8 @@ public expect class LocalDateTime : Comparable<LocalDateTime> {
  * Equivalent to calling [DateTimeFormat.format] on [format] with `this`.
  *
  * See [LocalDateTime.Formats] and [LocalDateTime.Format] for predefined and custom formats.
+ *
+ * @sample kotlinx.datetime.test.samples.LocalDateTimeSamples.formatting
  */
 public fun LocalDateTime.format(format: DateTimeFormat<LocalDateTime>): String = format.format(this)
 

core/common/test/samples/ClockSamples.kt

@@ -20,7 +20,7 @@ class ClockSamples {
     @Test
     fun todayIn() {
         val clock = object : Clock {
-            override fun now(): Instant = Instant.parse("2020-01-01T12:00:00Z")
+            override fun now(): Instant = Instant.parse("2020-01-01T02:00:00Z")
         }
         check(clock.todayIn(TimeZone.UTC) == LocalDate(2020, 1, 1))
         check(clock.todayIn(TimeZone.of("America/New_York")) == LocalDate(2019, 12, 31))