[glib: 1/2] gdate: Clarify the documentation for g_date_new_dmy() and new_julian()

[Emmanuele Bassi <ebassi src gnome org>]

commit fe0346a172e602f4d9849f0e4aed1e05bb4c6359
Author: Philip Withnall <pwithnall endlessos org>
Date:   Wed Nov 3 10:47:38 2021 +0000

    gdate: Clarify the documentation for g_date_new_dmy() and new_julian()
    
    The documentation about validity did not match the code. Since the code
    hasn’t changed in a long time (since 1998 or 2011), change the
    documentation to match it.
    
    Signed-off-by: Philip Withnall <pwithnall endlessos org>
    
    Fixes: #2520

 glib/gdate.c | 22 ++++++++++++++--------
 1 file changed, 14 insertions(+), 8 deletions(-)
---
diff --git a/glib/gdate.c b/glib/gdate.c
index 5feb090c4..8759cb4cd 100644
--- a/glib/gdate.c
+++ b/glib/gdate.c
@@ -288,11 +288,14 @@ g_date_new (void)
  * @month: month of the year
  * @year: year
  *
- * Like g_date_new(), but also sets the value of the date. Assuming the
- * day-month-year triplet you pass in represents an existing day, the
- * returned date will be valid.
+ * Create a new #GDate representing the given day-month-year triplet.
  *
- * Returns: a newly-allocated #GDate initialized with @day, @month, and @year
+ * The triplet you pass in must represent a valid date. Use g_date_valid_dmy()
+ * if needed to validate it. The returned #GDate is guaranteed to be non-%NULL
+ * and valid.
+ *
+ * Returns: (transfer full) (not nullable): a newly-allocated #GDate
+ *   initialized with @day, @month, and @year
  */
 GDate*
 g_date_new_dmy (GDateDay   day, 
@@ -320,11 +323,14 @@ g_date_new_dmy (GDateDay   day,
  * g_date_new_julian:
  * @julian_day: days since January 1, Year 1
  *
- * Like g_date_new(), but also sets the value of the date. Assuming the
- * Julian day number you pass in is valid (greater than 0, less than an
- * unreasonably large number), the returned date will be valid.
+ * Create a new #GDate representing the given Julian date.
+ *
+ * The @julian_day you pass in must be valid. Use g_date_valid_julian() if
+ * needed to validate it. The returned #GDate is guaranteed to be non-%NULL and
+ * valid.
  *
- * Returns: a newly-allocated #GDate initialized with @julian_day
+ * Returns: (transfer full) (not nullable): a newly-allocated #GDate initialized
+ *   with @julian_day
  */
 GDate*
 g_date_new_julian (guint32 julian_day)