[glib] gdatetime: Clarify documentation about clamping on addition

[Philip Withnall <pwithnall src gnome org>]

commit 11909c67d120ef015551e287331fffbeaae7a98e
Author: Philip Withnall <withnall endlessm com>
Date:   Wed Feb 28 15:30:40 2018 +0000

    gdatetime: Clarify documentation about clamping on addition
    
    If adding months or years to a date, the day of the month of the result
    is supposed to be the same as in the input — but that doesn’t work if
    that day doesn’t exist in the result month.
    
    Clarify the documentation about what happens here (the day of the month
    is clamped to the length of that month).
    
    Signed-off-by: Philip Withnall <withnall endlessm com>
    Reviewed-by: nobody

 glib/gdatetime.c | 8 ++++++++
 1 file changed, 8 insertions(+)
---
diff --git a/glib/gdatetime.c b/glib/gdatetime.c
index 85359ac00..6b9500cb6 100644
--- a/glib/gdatetime.c
+++ b/glib/gdatetime.c
@@ -1658,6 +1658,9 @@ g_date_time_add (GDateTime *datetime,
  * Creates a copy of @datetime and adds the specified number of years to the
  * copy. Add negative values to subtract years.
  *
+ * As with g_date_time_add_months(), if the resulting date would be 29th
+ * February on a non-leap year, the day will be clamped to 28th February.
+ *
  * Returns: the newly created #GDateTime which should be freed with
  *   g_date_time_unref().
  *
@@ -1693,6 +1696,11 @@ g_date_time_add_years (GDateTime *datetime,
  * Creates a copy of @datetime and adds the specified number of months to the
  * copy. Add negative values to subtract months.
  *
+ * The day of the month of the resulting #GDateTime is clamped to the number
+ * of days in the updated calendar month. For example, if adding 1 month to
+ * 31st January 2018, the result would be 28th February 2018. In 2020 (a leap
+ * year), the result would be 29th February.
+ *
  * Returns: the newly created #GDateTime which should be freed with
  *   g_date_time_unref().
  *