Further improve consistency in KDocs (#111)

core/src/commonMain/kotlin/io/islandtime/Date.kt

@@ -11,7 +11,7 @@ import io.islandtime.ranges.DateRange
 /**
  * A date in an ambiguous region.
  *
- * @constructor Create a [Date] from a year, month, and day of month.
+ * @constructor Creates a [Date] from a year, month, and day of month.
  * @param year the year
  * @param month the month
  * @param day the day of the month
@@ -31,7 +31,7 @@ class Date(
     }
 
     /**
-     * Create a [Date] from a year, ISO month number, and day of month.
+     * Creates a [Date] from a year, ISO month number, and day of month.
      * @param year the year
      * @param monthNumber the ISO month number, from 1-12
      * @param day the day of the month
@@ -58,7 +58,7 @@ class Date(
     val dayOfMonth: Int get() = day
 
     /**
-     * The day of the year -- also known as the ordinal date in ISO-8601.
+     * The day of the year.
      */
     val dayOfYear: Int get() = month.firstDayOfYearIn(year) + dayOfMonth - 1
 
@@ -289,24 +289,24 @@ class Date(
 
     companion object {
         /**
-         * The smallest supported [Date], which can be used as a "far past" sentinel.
+         * The earliest supported [Date], which can be used as a "far past" sentinel.
          */
         val MIN = Date(Year.MIN_VALUE, Month.JANUARY, 1)
 
         /**
-         * The largest supported [Date], which can be used as a "far future" sentinel.
+         * The latest supported [Date], which can be used as a "far future" sentinel.
          */
         val MAX = Date(Year.MAX_VALUE, Month.DECEMBER, 31)
 
         /**
-         * Create a [Date] from a duration of days relative to the Unix epoch of 1970-01-01.
+         * Creates a [Date] from a duration of days relative to the Unix epoch of 1970-01-01.
          * @param days the number of days relative to the Unix epoch
          * @throws DateTimeException if outside of the supported date range
          */
         fun fromDaysSinceUnixEpoch(days: LongDays): Date = fromDayOfUnixEpoch(days.value)
 
         /**
-         * Create a [Date] from the day of the Unix epoch.
+         * Creates a [Date] from the day of the Unix epoch.
          * @param day the day of the Unix epoch
          * @throws DateTimeException if outside of the supported date range
          */
@@ -330,7 +330,7 @@ class Date(
 }
 
 /**
- * Create a [Date] from a year and day of year
+ * Creates a [Date] from a year and day of year
  * @param year the year
  * @param dayOfYear the day of the calendar year
  * @throws DateTimeException if the year or day of year are invalid
@@ -347,7 +347,7 @@ fun Date(year: Int, dayOfYear: Int): Date {
 }
 
 /**
- * Convert an [Instant] into the [Date] represented by it at a particular UTC offset.
+ * Converts this instant to the corresponding [Date] at [offset].
  */
 fun Instant.toDateAt(offset: UtcOffset): Date {
     val adjustedSeconds = secondOfUnixEpoch + offset.totalSeconds.value
@@ -356,20 +356,20 @@ fun Instant.toDateAt(offset: UtcOffset): Date {
 }
 
 /**
- * Convert an [Instant] into the [Date] represented by it in a particular time zone.
+ * Converts this instant to the corresponding [Date] in [zone].
  */
 fun Instant.toDateAt(zone: TimeZone): Date {
     return this.toDateAt(zone.rules.offsetAt(this))
 }
 
 /**
- * Combine a [YearMonth] with a day of the month to create a [Date].
+ * Combines a [YearMonth] with a day of the month to create a [Date].
  * @param day the day of the month
  */
 fun YearMonth.atDay(day: Int) = Date(year, month, day)
 
 /**
- * Convert a string to a [Date].
+ * Converts a string to a [Date].
  *
  * The string is assumed to be an ISO-8601 calendar date in extended format. For example, `2010-10-05`. The output of
  * [Date.toString] can be safely parsed using this method.
@@ -380,7 +380,7 @@ fun YearMonth.atDay(day: Int) = Date(year, month, day)
 fun String.toDate() = toDate(DateTimeParsers.Iso.Extended.CALENDAR_DATE)
 
 /**
- * Convert a string to a [Date] using a specific parser.
+ * Converts a string to a [Date] using a specific parser.
  *
  * A set of predefined parsers can be found in [DateTimeParsers].
  *

core/src/commonMain/kotlin/io/islandtime/DateTime.kt

@@ -8,7 +8,7 @@ import io.islandtime.ranges.DateTimeInterval
 /**
  * A date and time of day in an ambiguous region.
  *
- * @constructor Create a [DateTime] by combining a [Date] and [Time].
+ * @constructor Creates a [DateTime] by combining a [Date] and [Time].
  * @param date the date
  * @param time the time
  */
@@ -20,7 +20,7 @@ class DateTime(
 ) : Comparable<DateTime> {
 
     /**
-     * Create a [DateTime].
+     * Creates a [DateTime].
      * @throws DateTimeException if the date-time is invalid
      */
     constructor(
@@ -34,7 +34,7 @@ class DateTime(
     ) : this(Date(year, month, day), Time(hour, minute, second, nanosecond))
 
     /**
-     * Create a [DateTime].
+     * Creates a [DateTime].
      * @throws DateTimeException if the date-time is invalid
      */
     constructor(
@@ -48,7 +48,7 @@ class DateTime(
     ) : this(year, monthNumber.toMonth(), day, hour, minute, second, nanosecond)
 
     /**
-     * Create a [DateTime].
+     * Creates a [DateTime].
      * @throws DateTimeException if the date-time is invalid
      */
     constructor(
@@ -101,7 +101,7 @@ class DateTime(
     inline val dayOfMonth: Int get() = date.dayOfMonth
 
     /**
-     * The day of the year -- also known as the ordinal date in ISO-8601.
+     * The day of the year.
      */
     inline val dayOfYear: Int get() = date.dayOfYear
 
@@ -592,17 +592,17 @@ class DateTime(
 
     companion object {
         /**
-         * The smallest supported [DateTime], which can be used as a "far past" sentinel.
+         * The earliest supported [DateTime], which can be used as a "far past" sentinel.
          */
         val MIN = DateTime(Date.MIN, Time.MIN)
 
         /**
-         * The largest supported [DateTime], which can be used as a "far future" sentinel.
+         * The latest supported [DateTime], which can be used as a "far future" sentinel.
          */
         val MAX = DateTime(Date.MAX, Time.MAX)
 
         /**
-         * Create a [DateTime] from a duration of milliseconds relative to the Unix epoch at [offset].
+         * Creates a [DateTime] from a duration of milliseconds relative to the Unix epoch at [offset].
          */
         fun fromMillisecondsSinceUnixEpoch(millisecondsSinceUnixEpoch: LongMilliseconds, offset: UtcOffset): DateTime {
             val localMilliseconds = millisecondsSinceUnixEpoch + offset.totalSeconds
@@ -615,7 +615,7 @@ class DateTime(
         }
 
         /**
-         * Create a [DateTime] from a duration of seconds relative to the Unix epoch at [offset], optionally, with some
+         * Creates a [DateTime] from a duration of seconds relative to the Unix epoch at [offset], optionally, with some
          * number of additional nanoseconds added to it.
          */
         fun fromSecondsSinceUnixEpoch(
@@ -635,14 +635,14 @@ class DateTime(
         }
 
         /**
-         * Create a [DateTime] from the millisecond of the Unix epoch at [offset].
+         * Creates a [DateTime] from the millisecond of the Unix epoch at [offset].
          */
         fun fromMillisecondOfUnixEpoch(millisecond: Long, offset: UtcOffset): DateTime {
             return fromMillisecondsSinceUnixEpoch(millisecond.milliseconds, offset)
         }
 
         /**
-         * Create a [DateTime] from the second of the Unix epoch at [offset] and optionally, the nanosecond of the
+         * Creates a [DateTime] from the second of the Unix epoch at [offset] and optionally, the nanosecond of the
          * second.
          */
         fun fromSecondOfUnixEpoch(second: Long, nanosecond: Int = 0, offset: UtcOffset): DateTime {
@@ -670,12 +670,12 @@ class DateTime(
 }
 
 /**
- * Combine a [Date] with a [Time] to create a [DateTime].
+ * Combines a [Date] with a [Time] to create a [DateTime].
  */
 infix fun Date.at(time: Time) = DateTime(this, time)
 
 /**
- * Combine a [Date] with a time to create a [DateTime].
+ * Combines a [Date] with a time to create a [DateTime].
  */
 fun Date.atTime(hour: Int, minute: Int, second: Int = 0, nanosecond: Int = 0): DateTime {
     return DateTime(this, Time(hour, minute, second, nanosecond))
@@ -710,7 +710,7 @@ val Date.endOfDay: DateTime get() = DateTime(this, Time.MAX)
 fun String.toDateTime() = toDateTime(DateTimeParsers.Iso.Extended.DATE_TIME)
 
 /**
- * Convert a string to a [DateTime] using a specific parser.
+ * Converts a string to a [DateTime] using a specific parser.
  *
  * A set of predefined parsers can be found in [DateTimeParsers].
  *

core/src/commonMain/kotlin/io/islandtime/DayOfWeek.kt

@@ -71,22 +71,22 @@ enum class DayOfWeek {
     }
 
     /**
-     * Add days to this day of the week, wrapping when the beginning or end of the week is reached.
+     * Adds days to this day of the week, wrapping when the beginning or end of the week is reached.
      */
     operator fun plus(days: IntDays) = plus(days.value % DAYS_PER_WEEK)
 
     /**
-     * Add days to this day of the week, wrapping when the beginning or end of the week is reached.
+     * Adds days to this day of the week, wrapping when the beginning or end of the week is reached.
      */
     operator fun plus(days: LongDays) = plus((days.value % DAYS_PER_WEEK).toInt())
 
     /**
-     * Subtract days from this day of the week, wrapping when the beginning or end of the week is reached.
+     * Subtracts days from this day of the week, wrapping when the beginning or end of the week is reached.
      */
     operator fun minus(days: IntDays) = plus(-(days.value % DAYS_PER_WEEK))
 
     /**
-     * Subtract days from this day of the week, wrapping when the beginning or end of the week is reached.
+     * Subtracts days from this day of the week, wrapping when the beginning or end of the week is reached.
      */
     operator fun minus(days: LongDays) = plus(-(days.value % DAYS_PER_WEEK).toInt())
 
@@ -101,7 +101,7 @@ enum class DayOfWeek {
 }
 
 /**
- * Convert an ISO day of week number to a [DayOfWeek].
+ * Converts an ISO day of week number to a [DayOfWeek].
  *
  * The ISO week starts on Monday (1) and ends on Sunday (7).
  */
@@ -110,7 +110,7 @@ fun Int.toDayOfWeek(): DayOfWeek {
 }
 
 /**
- * Convert a day of week number (1-7) to a [DayOfWeek] according to the week definition provided by [settings].
+ * Converts a day of week number (1-7) to a [DayOfWeek] using the week definition provided by [settings].
  */
 fun Int.toDayOfWeek(settings: WeekSettings): DayOfWeek {
     return settings.firstDayOfWeek + (checkValidDayOfWeek(this) - 1).days

core/src/commonMain/kotlin/io/islandtime/Instant.kt

@@ -204,12 +204,12 @@ class Instant private constructor(
         private const val MAX_SECOND = 31556889864403199L
 
         /**
-         * The smallest supported [Instant], which can be used as a "far past" sentinel.
+         * The earliest supported [Instant], which can be used as a "far past" sentinel.
          */
         val MIN = fromSecondOfUnixEpoch(MIN_SECOND)
 
         /**
-         * The largest supported [Instant], which can be used as a "far future" sentinel.
+         * The latest supported [Instant], which can be used as a "far future" sentinel.
          */
         val MAX = fromSecondOfUnixEpoch(MAX_SECOND, 999_999_999L)
 
@@ -219,21 +219,21 @@ class Instant private constructor(
         val UNIX_EPOCH = fromSecondOfUnixEpoch(0L)
 
         /**
-         * Create an [Instant] from the second of the Unix epoch.
+         * Creates an [Instant] from the second of the Unix epoch.
          */
         fun fromSecondOfUnixEpoch(second: Long): Instant {
             return Instant(second, 0)
         }
 
         /**
-         * Create an [Instant] from the second of the Unix epoch.
+         * Creates an [Instant] from the second of the Unix epoch.
          */
         fun fromSecondOfUnixEpoch(second: Long, nanosecond: Int): Instant {
             return fromSecondOfUnixEpoch(second, nanosecond.toLong())
         }
 
         /**
-         * Create an [Instant] from the second of the Unix epoch.
+         * Creates an [Instant] from the second of the Unix epoch.
          */
         fun fromSecondOfUnixEpoch(second: Long, nanosecond: Long): Instant {
             val newSecond = second plusExact (nanosecond floorDiv NANOSECONDS_PER_SECOND)
@@ -243,7 +243,7 @@ class Instant private constructor(
         }
 
         /**
-         * Create an [Instant] from the millisecond of the Unix epoch.
+         * Creates an [Instant] from the millisecond of the Unix epoch.
          */
         fun fromMillisecondOfUnixEpoch(millisecond: Long): Instant {
             val second = millisecond floorDiv MILLISECONDS_PER_SECOND
@@ -290,35 +290,35 @@ class Instant private constructor(
 }
 
 /**
- * Create the [Instant] represented by a number of seconds relative to the Unix epoch of 1970-01-01T00:00Z.
+ * Creates the [Instant] represented by a number of seconds relative to the Unix epoch of 1970-01-01T00:00Z.
  */
 fun Instant(secondsSinceUnixEpoch: LongSeconds) = Instant.fromSecondOfUnixEpoch(secondsSinceUnixEpoch.value)
 
 /**
- * Create the [Instant] represented by a number of seconds and additional nanoseconds relative to the Unix epoch of
+ * Creates the [Instant] represented by a number of seconds and additional nanoseconds relative to the Unix epoch of
  * 1970-01-01T00:00Z.
  */
 fun Instant(secondsSinceUnixEpoch: LongSeconds, nanosecondAdjustment: IntNanoseconds): Instant {
     return Instant.fromSecondOfUnixEpoch(secondsSinceUnixEpoch.value, nanosecondAdjustment.value)
 }
 
 /**
- * Create the [Instant] represented by a number of seconds and additional nanoseconds relative to the Unix epoch of
+ * Creates the [Instant] represented by a number of seconds and additional nanoseconds relative to the Unix epoch of
  * 1970-01-01T00:00Z.
  */
 fun Instant(secondsSinceUnixEpoch: LongSeconds, nanosecondAdjustment: LongNanoseconds): Instant {
     return Instant.fromSecondOfUnixEpoch(secondsSinceUnixEpoch.value, nanosecondAdjustment.value)
 }
 
 /**
- * Create the [Instant] represented by a number of milliseconds relative to the Unix epoch of 1970-01-01T00:00Z.
+ * Creates the [Instant] represented by a number of milliseconds relative to the Unix epoch of 1970-01-01T00:00Z.
  */
 fun Instant(millisecondsSinceUnixEpoch: LongMilliseconds): Instant {
     return Instant.fromMillisecondOfUnixEpoch(millisecondsSinceUnixEpoch.value)
 }
 
 /**
- * Convert a string to an [Instant].
+ * Converts a string to an [Instant].
  *
  * The string is assumed to be an ISO-8601 UTC date-time representation in extended format. For example,
  * `2010-10-05T18:30Z` or `2010-10-05T18:30:00.123456789Z`. The output of [Instant.toString] can be safely parsed
@@ -330,7 +330,7 @@ fun Instant(millisecondsSinceUnixEpoch: LongMilliseconds): Instant {
 fun String.toInstant() = toInstant(DateTimeParsers.Iso.Extended.INSTANT)
 
 /**
- * Convert a string to an [Instant] using a specific parser.
+ * Converts a string to an [Instant] using a specific parser.
  *
  * A set of predefined parsers can be found in [DateTimeParsers].
  *

core/src/commonMain/kotlin/io/islandtime/IslandTime.kt

@@ -36,7 +36,7 @@ object IslandTime {
         }
 
     /**
-     * Initialize Island Time.
+     * Initializes Island Time.
      *
      * This method should be called prior to any of use of the library, usually during an application's initialization
      * process. If Island Time is not explicitly initialized, the [PlatformTimeZoneRulesProvider] and all other default
@@ -49,7 +49,7 @@ object IslandTime {
     }
 
     /**
-     * Initialize Island Time with a specific time zone rules provider, leaving all other settings in their default
+     * Initializes Island Time with a specific time zone rules provider, leaving all other settings in their default
      * state.
      *
      * This method should be called prior to any of use of the library, usually during an application's initialization
@@ -64,7 +64,7 @@ object IslandTime {
     }
 
     /**
-     * Reset Island Time to an uninitialized state.
+     * Resets Island Time to an uninitialized state.
      *
      * This method is intended to be used to clean up custom providers in tests. It shouldn't be necessary to call this
      * in production.