Provide a one-line description for every sample

Author: dkhalanskyjb

core/common/test/samples/ClockSamples.kt

@@ -11,6 +11,7 @@ import kotlin.test.*
 class ClockSamples {
     @Test
     fun system() {
+        // Getting the current date and time
         val zone = TimeZone.of("Europe/Berlin")
         val currentInstant = Clock.System.now()
         val currentLocalDateTime = currentInstant.toLocalDateTime(zone)
@@ -19,6 +20,7 @@ class ClockSamples {
 
     @Test
     fun todayIn() {
+        // Getting the current date in different time zones
         val clock = object : Clock {
             override fun now(): Instant = Instant.parse("2020-01-01T02:00:00Z")
         }

core/common/test/samples/DateTimePeriodSamples.kt

@@ -14,6 +14,7 @@ class DateTimePeriodSamples {
 
     @Test
     fun construction() {
+        // Constructing a DateTimePeriod using its constructor function
         val period = DateTimePeriod(years = 5, months = 21, days = 36, seconds = 3601)
         check(period.years == 6) // 5 years + (21 months / 12)
         check(period.months == 9) // 21 months % 12
@@ -27,13 +28,15 @@ class DateTimePeriodSamples {
 
     @Test
     fun simpleParsingAndFormatting() {
+        // Parsing and formatting a DateTimePeriod
         val string = "-P2M-3DT-4H"
         val period = DateTimePeriod.parse(string)
         check(period.toString() == "P-2M3DT4H")
     }
 
     @Test
     fun valueNormalization() {
+        // Reading the normalized values that make up a DateTimePeriod
         val period = DateTimePeriod(
             years = -12, months = 122, days = -1440,
             hours = 400, minutes = -80, seconds = 123, nanoseconds = -123456789
@@ -52,13 +55,15 @@ class DateTimePeriodSamples {
 
     @Test
     fun toStringSample() {
+        // Formatting a DateTimePeriod to a string
         check(DateTimePeriod(years = 1, months = 2, days = 3, hours = 4, minutes = 5, seconds = 6, nanoseconds = 7).toString() == "P1Y2M3DT4H5M6.000000007S")
         check(DateTimePeriod(months = 14, days = -16, hours = 5).toString() == "P1Y2M-16DT5H")
         check(DateTimePeriod(months = -2, days = -16, hours = -5).toString() == "-P2M16DT5H")
     }
 
     @Test
     fun parsing() {
+        // Parsing a string representation of a DateTimePeriod
         DateTimePeriod.parse("P1Y2M3DT4H5M6.000000007S").apply {
             check(years == 1)
             check(months == 2)
@@ -84,6 +89,7 @@ class DateTimePeriodSamples {
 
     @Test
     fun constructorFunction() {
+        // Constructing a DateTimePeriod using its constructor function
         val dateTimePeriod = DateTimePeriod(months = 16, days = -60, hours = 16, minutes = -61)
         check(dateTimePeriod.years == 1) // months overflowed to years
         check(dateTimePeriod.months == 4) // 16 months % 12
@@ -96,6 +102,7 @@ class DateTimePeriodSamples {
 
     @Test
     fun durationToDateTimePeriod() {
+        // Converting a Duration to a DateTimePeriod that only has time-based components
         check(130.minutes.toDateTimePeriod() == DateTimePeriod(minutes = 130))
         check(2.days.toDateTimePeriod() == DateTimePeriod(days = 0, hours = 48))
     }
@@ -104,6 +111,7 @@ class DateTimePeriodSamples {
 
         @Test
         fun simpleParsingAndFormatting() {
+            // Parsing and formatting a DatePeriod
             val datePeriod1 = DatePeriod(years = 1, days = 3)
             val string = datePeriod1.toString()
             check(string == "P1Y3D")
@@ -113,6 +121,7 @@ class DateTimePeriodSamples {
 
         @Test
         fun construction() {
+            // Constructing a DatePeriod using its constructor
             val datePeriod = DatePeriod(years = 1, months = 16, days = 60)
             check(datePeriod.years == 2) // 1 year + (16 months / 12)
             check(datePeriod.months == 4) // 16 months % 12
@@ -126,6 +135,7 @@ class DateTimePeriodSamples {
 
         @Test
         fun parsing() {
+            // Parsing a string representation of a DatePeriod
             // ISO duration strings are supported:
             val datePeriod = DatePeriod.parse("P1Y16M60D")
             check(datePeriod == DatePeriod(years = 2, months = 4, days = 60))

core/common/test/samples/DateTimeUnitSamples.kt

@@ -12,6 +12,7 @@ import kotlin.time.Duration.Companion.hours
 class DateTimeUnitSamples {
     @Test
     fun construction() {
+        // Constructing various measurement units
         check(DateTimeUnit.HOUR == DateTimeUnit.TimeBased(nanoseconds = 60 * 60 * 1_000_000_000L))
         check(DateTimeUnit.WEEK == DateTimeUnit.DayBased(days = 7))
         check(DateTimeUnit.WEEK * 2 == DateTimeUnit.DayBased(days = 14))
@@ -20,12 +21,14 @@ class DateTimeUnitSamples {
 
     @Test
     fun multiplication() {
+        // Obtaining a measurement unit that's several times larger than another one
         val twoWeeks = DateTimeUnit.WEEK * 2
         check(twoWeeks.days == 14)
     }
 
     @Test
     fun timeBasedUnit() {
+        // Constructing various time-based measurement units
         val halfDay = DateTimeUnit.TimeBased(nanoseconds = 12 * 60 * 60 * 1_000_000_000L)
         check(halfDay.nanoseconds == 12 * 60 * 60 * 1_000_000_000L)
         check(halfDay.duration == 12.hours)
@@ -36,6 +39,7 @@ class DateTimeUnitSamples {
 
     @Test
     fun dayBasedUnit() {
+        // Constructing various day-based measurement units
         val iteration = DateTimeUnit.DayBased(days = 14)
         check(iteration.days == 14)
         check(iteration == DateTimeUnit.DAY * 14)
@@ -44,6 +48,7 @@ class DateTimeUnitSamples {
 
     @Test
     fun monthBasedUnit() {
+        // Constructing various month-based measurement units
         val halfYear = DateTimeUnit.MonthBased(months = 6)
         check(halfYear.months == 6)
         check(halfYear == DateTimeUnit.QUARTER * 2)

core/common/test/samples/DayOfWeekSamples.kt

@@ -12,6 +12,7 @@ class DayOfWeekSamples {
 
     @Test
     fun usage() {
+        // Providing different behavior based on what day of the week it is today
         val today = Clock.System.todayIn(TimeZone.currentSystemDefault())
         when (today.dayOfWeek) {
             DayOfWeek.MONDAY -> check(today.dayOfWeek.isoDayNumber == 1)
@@ -27,6 +28,7 @@ class DayOfWeekSamples {
 
     @Test
     fun isoDayNumber() {
+        // Getting the ISO day-of-week number
         check(DayOfWeek.MONDAY.isoDayNumber == 1)
         check(DayOfWeek.TUESDAY.isoDayNumber == 2)
         // ...
@@ -35,6 +37,7 @@ class DayOfWeekSamples {
 
     @Test
     fun constructorFunction() {
+        // Constructing a DayOfWeek from the ISO day-of-week number
         check(DayOfWeek(isoDayNumber = 1) == DayOfWeek.MONDAY)
         check(DayOfWeek(isoDayNumber = 2) == DayOfWeek.TUESDAY)
         // ...