Update the docs

Author: dkhalanskyjb

core/common/src/LocalDate.kt

@@ -81,6 +81,9 @@ public expect class LocalDate : Comparable<LocalDate> {
          * - [month] `1..12`
          * - [day] `1..31`, the upper bound can be less, depending on the month
          *
+         * Use `LocalDate(year, month, day) to throw an exception
+         * instead of returning `null` when the parameters are invalid.
+         *
          * @sample kotlinx.datetime.test.samples.LocalDateSamples.createOrNullMonthNumber
          */
         public fun createOrNull(year: Int, month: Int, day: Int): LocalDate?
@@ -95,6 +98,9 @@ public expect class LocalDate : Comparable<LocalDate> {
          * - [month] all values of the [Month] enum
          * - [day] `1..31`, the upper bound can be less, depending on the month
          *
+         * Use `LocalDate(year, month, day) to throw an exception
+         * instead of returning `null` when the parameters are invalid.
+         *
          * @sample kotlinx.datetime.test.samples.LocalDateSamples.createOrNull
          */
         public fun createOrNull(year: Int, month: Month, day: Int): LocalDate?
@@ -206,6 +212,8 @@ public expect class LocalDate : Comparable<LocalDate> {
      *
      * @throws IllegalArgumentException if any parameter is out of range or if [day] is invalid for the
      * given [month] and [year].
+     * @see createOrNull for a version that returns `null` instead of throwing an exception
+     * when the parameters are invalid.
      * @sample kotlinx.datetime.test.samples.LocalDateSamples.constructorFunctionMonthNumber
      */
     public constructor(year: Int, month: Int, day: Int)
@@ -221,6 +229,8 @@ public expect class LocalDate : Comparable<LocalDate> {
      *
      * @throws IllegalArgumentException if any parameter is out of range or if [day] is invalid for the
      * given [month] and [year].
+     * @see createOrNull for a version that returns `null` instead of throwing an exception
+     * when the parameters are invalid.
      * @sample kotlinx.datetime.test.samples.LocalDateSamples.constructorFunction
      */
     public constructor(year: Int, month: Month, day: Int)

core/common/src/LocalDateTime.kt

@@ -130,6 +130,9 @@ public expect class LocalDateTime : Comparable<LocalDateTime> {
          * - [second] `0..59`
          * - [nanosecond] `0..999_999_999`
          *
+         * Use `LocalDateTime(year, month, day, hour, minute, second, nanosecond)`
+         * to throw an exception instead of returning `null` when the parameters are invalid.
+         *
          * @sample kotlinx.datetime.test.samples.LocalDateTimeSamples.createOrNull
          */
         public fun createOrNull(
@@ -156,6 +159,9 @@ public expect class LocalDateTime : Comparable<LocalDateTime> {
          * - [second] `0..59`
          * - [nanosecond] `0..999_999_999`
          *
+         * Use `LocalDateTime(year, month, day, hour, minute, second, nanosecond)`
+         * to throw an exception instead of returning `null` when the parameters are invalid.
+         *
          * @sample kotlinx.datetime.test.samples.LocalDateTimeSamples.createOrNullWithMonth
          */
         public fun createOrNull(
@@ -268,6 +274,7 @@ public expect class LocalDateTime : Comparable<LocalDateTime> {
      *
      * @throws IllegalArgumentException if any parameter is out of range
      * or if [day] is invalid for the given [monthNumber] and [year].
+     * @see createOrNull for a version that returns `null` instead of throwing an exception when the parameters are invalid.
      *
      * @sample kotlinx.datetime.test.samples.LocalDateTimeSamples.constructorFunctionWithMonthNumber
      */
@@ -296,6 +303,7 @@ public expect class LocalDateTime : Comparable<LocalDateTime> {
      *
      * @throws IllegalArgumentException if any parameter is out of range,
      * or if [day] is invalid for the given [month] and [year].
+     * @see createOrNull for a version that returns `null` instead of throwing an exception when the parameters are invalid.
      *
      * @sample kotlinx.datetime.test.samples.LocalDateTimeSamples.constructorFunction
      */
@@ -312,6 +320,7 @@ public expect class LocalDateTime : Comparable<LocalDateTime> {
     /**
      * Constructs a [LocalDateTime] instance by combining the given [date] and [time] parts.
      *
+     * @see createOrNull for a version that returns `null` instead of throwing an exception when the parameters are invalid.
      * @sample kotlinx.datetime.test.samples.LocalDateTimeSamples.fromDateAndTime
      */
     public constructor(date: LocalDate, time: LocalTime)

core/common/src/LocalTime.kt

@@ -94,6 +94,9 @@ public expect class LocalTime : Comparable<LocalTime> {
          * - [second] `0..59`
          * - [nanosecond] `0..999_999_999`
          *
+         * Use `LocalTime(hour, minute, second, nanosecond)`
+         * to throw an exception instead of returning `null` when the parameters are invalid.
+         *
          * @sample kotlinx.datetime.test.samples.LocalTimeSamples.createOrNull
          */
         public fun createOrNull(hour: Int, minute: Int, second: Int = 0, nanosecond: Int = 0): LocalTime?
@@ -244,6 +247,7 @@ public expect class LocalTime : Comparable<LocalTime> {
      * - [nanosecond] `0..999_999_999`
      *
      * @throws IllegalArgumentException if any parameter is out of range.
+     * @see createOrNull for a version that returns `null` instead of throwing an exception when the parameters are invalid.
      * @sample kotlinx.datetime.test.samples.LocalTimeSamples.constructorFunction
      */
     public constructor(hour: Int, minute: Int, second: Int = 0, nanosecond: Int = 0)

core/common/src/UtcOffset.kt

@@ -91,8 +91,9 @@ public expect class UtcOffset {
          * However, the non-null component of the highest order can exceed these bounds,
          * for example, `UtcOffset.createOrNull(minutes = 241)` and `UtcOffset.createOrNull(seconds = -3600)` are both valid.
          *
-         * @return the [UtcOffset] with the specified components, or `null` if the components are invalid
-         * or the resulting `UtcOffset` value is outside of range `±18:00`.
+         * Use `UtcOffset(hours, minutes, seconds)` to throw an exception instead of returning `null`
+         * when the parameters are invalid.
+         *
          * @sample kotlinx.datetime.test.samples.UtcOffsetSamples.createOrNull
          */
         public fun createOrNull(hours: Int? = null, minutes: Int? = null, seconds: Int? = null): UtcOffset?
@@ -230,6 +231,7 @@ public fun UtcOffset.format(format: DateTimeFormat<UtcOffset>): String = format.
  * @throws IllegalArgumentException if a component exceeds its bounds when a higher order component is specified.
  * @throws IllegalArgumentException if components have different signs.
  * @throws IllegalArgumentException if the resulting `UtcOffset` value is outside of range `±18:00`.
+ * @see UtcOffset.createOrNull for a version that returns `null` instead of throwing an exception when the parameters are invalid.
  * @sample kotlinx.datetime.test.samples.UtcOffsetSamples.constructorFunction
  */
 public expect fun UtcOffset(hours: Int? = null, minutes: Int? = null, seconds: Int? = null): UtcOffset