From fe0346a172e602f4d9849f0e4aed1e05bb4c6359 Mon Sep 17 00:00:00 2001 From: Philip Withnall Date: Wed, 3 Nov 2021 10:47:38 +0000 Subject: [PATCH] gdate: Clarify the documentation for g_date_new_dmy() and new_julian() MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 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. * - * Returns: a newly-allocated #GDate initialized with @julian_day + * 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: (transfer full) (not nullable): a newly-allocated #GDate initialized + * with @julian_day */ GDate* g_date_new_julian (guint32 julian_day)