From 7b4d00e0a465af5f5aba6fd9e9b2e0a0355419c8 Mon Sep 17 00:00:00 2001
From: Matthias Clasen <mclasen@redhat.com>
Date: Mon, 25 Sep 2023 07:45:24 -0400
Subject: [PATCH] docs: Move GDateTime SECTION

Move the contents to the struct comment.

Helps: #3037
---
 glib/gdatetime.c | 33 ---------------------------------
 glib/gdatetime.h | 26 +++++++++++++++++++++++++-
 2 files changed, 25 insertions(+), 34 deletions(-)

diff --git a/glib/gdatetime.c b/glib/gdatetime.c
index d04b0abf1..1c854692a 100644
--- a/glib/gdatetime.c
+++ b/glib/gdatetime.c
@@ -89,39 +89,6 @@
 #endif
 #endif /* !G_OS_WIN32 */
 
-/**
- * SECTION:date-time
- * @title: GDateTime
- * @short_description: a structure representing Date and Time
- * @see_also: #GTimeZone
- *
- * #GDateTime is a structure that combines a Gregorian date and time
- * into a single structure.  It provides many conversion and methods to
- * manipulate dates and times.  Time precision is provided down to
- * microseconds and the time can range (proleptically) from 0001-01-01
- * 00:00:00 to 9999-12-31 23:59:59.999999.  #GDateTime follows POSIX
- * time in the sense that it is oblivious to leap seconds.
- *
- * #GDateTime is an immutable object; once it has been created it cannot
- * be modified further.  All modifiers will create a new #GDateTime.
- * Nearly all such functions can fail due to the date or time going out
- * of range, in which case %NULL will be returned.
- *
- * #GDateTime is reference counted: the reference count is increased by calling
- * g_date_time_ref() and decreased by calling g_date_time_unref(). When the
- * reference count drops to 0, the resources allocated by the #GDateTime
- * structure are released.
- *
- * Many parts of the API may produce non-obvious results.  As an
- * example, adding two months to January 31st will yield March 31st
- * whereas adding one month and then one month again will yield either
- * March 28th or March 29th.  Also note that adding 24 hours is not
- * always the same as adding one day (since days containing daylight
- * savings time transitions are either 23 or 25 hours in length).
- *
- * #GDateTime is available since GLib 2.26.
- */
-
 struct _GDateTime
 {
   /* Microsecond timekeeping within Day */
diff --git a/glib/gdatetime.h b/glib/gdatetime.h
index 4312433bd..b257b057f 100644
--- a/glib/gdatetime.h
+++ b/glib/gdatetime.h
@@ -91,7 +91,31 @@ typedef gint64 GTimeSpan;
 /**
  * GDateTime:
  *
- * An opaque structure that represents a date and time, including a time zone.
+ * `GDateTime` is a structure that combines a Gregorian date and time
+ * into a single structure.
+ *
+ * `GDateTime` provides many conversion and methods to manipulate dates and times.
+ * Time precision is provided down to microseconds and the time can range
+ * (proleptically) from 0001-01-01 00:00:00 to 9999-12-31 23:59:59.999999.
+ * `GDateTime` follows POSIX time in the sense that it is oblivious to leap
+ * seconds.
+ *
+ * `GDateTime` is an immutable object; once it has been created it cannot
+ * be modified further. All modifiers will create a new `GDateTime`.
+ * Nearly all such functions can fail due to the date or time going out
+ * of range, in which case %NULL will be returned.
+ *
+ * `GDateTime` is reference counted: the reference count is increased by calling
+ * [metohd@GLib.DateTime.ref] and decreased by calling [method@GLib.DateTime.unref].
+ * When the reference count drops to 0, the resources allocated by the `GDateTime`
+ * structure are released.
+ *
+ * Many parts of the API may produce non-obvious results. As an
+ * example, adding two months to January 31st will yield March 31st
+ * whereas adding one month and then one month again will yield either
+ * March 28th or March 29th.  Also note that adding 24 hours is not
+ * always the same as adding one day (since days containing daylight
+ * savings time transitions are either 23 or 25 hours in length).
  *
  * Since: 2.26
  */