Deprecate DatePeriod.plus and DateTimePeriod.plus (#449)

Fixes #381

Author: dkhalanskyjb

core/common/src/DateTimePeriod.kt

@@ -581,6 +581,10 @@ public fun Duration.toDateTimePeriod(): DateTimePeriod = buildDateTimePeriod(tot
  *
  * @throws DateTimeArithmeticException if arithmetic overflow happens.
  */
+@Deprecated(
+    "Adding periods is not a well-defined operation. See https://github.com/Kotlin/kotlinx-datetime/issues/381",
+    level = DeprecationLevel.WARNING
+)
 public operator fun DateTimePeriod.plus(other: DateTimePeriod): DateTimePeriod = buildDateTimePeriod(
     safeAdd(totalMonths, other.totalMonths),
     safeAdd(days, other.days),
@@ -595,6 +599,10 @@ public operator fun DateTimePeriod.plus(other: DateTimePeriod): DateTimePeriod =
  *
  * @throws DateTimeArithmeticException if arithmetic overflow happens.
  */
+@Deprecated(
+    "Adding periods is not a well-defined operation. See https://github.com/Kotlin/kotlinx-datetime/issues/381",
+    level = DeprecationLevel.WARNING
+)
 public operator fun DatePeriod.plus(other: DatePeriod): DatePeriod = DatePeriod(
     safeAdd(totalMonths, other.totalMonths),
     safeAdd(days, other.days),

core/common/test/DateTimePeriodTest.kt

@@ -148,14 +148,17 @@ class DateTimePeriodTest {
 
         val dp1 = DatePeriod(years = 1, months = 6)
 
-        assertEquals(DateTimePeriod(years = 10, days = 3, hours = 2), p1 + p2 + p3)
-        assertEquals(DatePeriod(years = 11, months = 6), dp1 + p1)
-        assertEquals(DatePeriod(years = 2, months = 12), dp1 + dp1)
-        assertEquals(DateTimePeriod(years = 1, months = 6, days = 3), p2 + dp1)
-
-        val dp2 = dp1 + p3 + p4
-        assertEquals(dp1, dp2)
-        assertTrue(dp2 is DatePeriod)
+        @Suppress("DEPRECATION")
+        run {
+            assertEquals(DateTimePeriod(years = 10, days = 3, hours = 2), p1 + p2 + p3)
+            assertEquals(DatePeriod(years = 11, months = 6), dp1 + p1)
+            assertEquals(DatePeriod(years = 2, months = 12), dp1 + dp1)
+            assertEquals(DateTimePeriod(years = 1, months = 6, days = 3), p2 + dp1)
+
+            val dp2 = dp1 + p3 + p4
+            assertEquals(dp1, dp2)
+            assertTrue(dp2 is DatePeriod)
+        }
     }
 
     @Test