Clarify setting DateTimeComponents.month

Author: dkhalanskyjb

core/common/src/format/DateTimeComponents.kt

@@ -274,8 +274,14 @@ public class DateTimeComponents internal constructor(internal val contents: Date
 
     /**
      * The month ([Month]) component of the date.
+     *
+     * This is a view of [monthNumber].
+     * Setting it will set [monthNumber], and getting it will return a [Month] instance if [monthNumber] is a valid
+     * month.
+     *
      * @throws IllegalArgumentException during getting if [monthNumber] is outside the `1..12` range.
      * @sample kotlinx.datetime.test.samples.format.DateTimeComponentsSamples.date
+     * @sample kotlinx.datetime.test.samples.format.DateTimeComponentsSamples.setMonth
      */
     public var month: Month?
         get() = monthNumber?.let { Month(it) }

core/common/test/samples/format/DateTimeComponentsSamples.kt

@@ -155,6 +155,17 @@ class DateTimeComponentsSamples {
         check(parsedDate.dayOfWeek == null)
     }
 
+    @Test
+    fun setMonth() {
+        val input = "Mon, 30 Jul 2008 11:05:30 GMT"
+        val parsed = DateTimeComponents.Formats.RFC_1123.parse(input)
+        check(parsed.monthNumber == 7)
+        check(parsed.month == Month.JULY)
+        parsed.month = Month.JUNE
+        check(parsed.monthNumber == 6)
+        check(parsed.month == Month.JUNE)
+    }
+
     @Test
     fun timeAmPm() {
         val format = DateTimeComponents.Format {